Grabbers
--------

Grabber is an abstraction for a device whose output is a stream of images.

There is currently V4L2 driver that implements a grabber.

Link with +-lgfxprim-grabbers+ or better +\`gfxprim-config --libs-grabbers`+.

TIP: For example usage see grabber link:example_v4l2.html[examples].

Grabber API
~~~~~~~~~~~

The grabber API consist of structure with callbacks. Every grabber
initialization yields pointer to this structure. Although is possible to call
these pointers directly it's not recommended and everybody should rather use
the inline functions instead.

The grabber API consist gp_grabber structure and of several functions:

[source,c]
-------------------------------------------------------------------------------
typdef struct gp_grabber {
	/*
         * Currently loaded frame.
         */
	gp_pixmap *frame;

	/*
         * Connection fd usable for select() or poll().
	 *
	 * Set to -1 if not available.
         */
        int fd;

	/* ... */
} gp_grabber;
-------------------------------------------------------------------------------

The frame is a pointer to currently loaded frame. Its content is undefined
until you start the grabber with 'gp_grabber_start()' and receive frame with
'gp_grabber_poll()'.

The 'fd' is a file descriptor suitable for select() or poll(). It's set to -1
if there is none.


[source,c]
-------------------------------------------------------------------------------
#include <grabbers/gp_grabber.h>
/* or */
#include <gfxprim.h>

void gp_grabber_exit(gp_grabber *backend);
-------------------------------------------------------------------------------

Exits the grabber, frees memory, unmaps memory mappings, closes file
descriptors etc...

[source,c]
-------------------------------------------------------------------------------
#include <grabbers/gp_grabber.h>
/* or */
#include <gfxprim.h>

int gp_grabber_start(struct gp_grabber *self);
-------------------------------------------------------------------------------

Starts a grabber. After calling this you can start retrieving frames with
'gp_grabber_poll()'.

Returns zero on success and non-zero on failure.

[source,c]
-------------------------------------------------------------------------------
#include <grabbers/gp_grabber.h>
/* or */
#include <gfxprim.h>

int gp_grabber_stop(struct gp_grabber *self);
-------------------------------------------------------------------------------

Stops a grabber. Call this when you doesn't need to receive frames but still
plan to use the grabber later.

Returns zero on success and non-zero on failure.

[source,c]
-------------------------------------------------------------------------------
#include <grabbers/gp_grabber.h>
/* or */
#include <gfxprim.h>

int gp_grabber_poll(struct gp_grabber *self);
-------------------------------------------------------------------------------

Once grabber is created you can call this function to receive a frame. If
grabber 'fd' is not -1 it's preferable to call it when select() or poll()
returns that data are available on the 'fd'.

This function returns non-zero if new frame was received and stored into the
'frame' pixmap. Otherwise zero is returned.

Grabber Initializations
~~~~~~~~~~~~~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#include <grabbers/gp_v4l2.h>
/* or */
#include <gfxprim.h>

struct gp_grabber *gp_grabber_v4l2_init(const char *device,
                                        unsigned int preferred_width,
                                        unsigned int preferred_height);
-------------------------------------------------------------------------------

Opens and initializes V4L2 device. The device is a path in +/dev+ filesystem
the first V4L2 device in your system should be +/dev/video0+.

The height and width are preferred values, you will most likely get frame by
that width and height, but the driver may return different values if chosen
width and height are not supported.

Returns either pointer to the initialized grabber or, in case of failure,
NULL and errno is set.

