doc/grabbers.txt

   1 Grabbers
   2 --------
   3
   4 Grabber is an abstraction for a device whose output is a stream of images.
   5
   6 There is currently V4L2 driver that implements a grabber.
   7
   8 Link with +-lgfxprim-grabbers+ or better +\`gfxprim-config --libs-grabbers`+.
   9
  10 TIP: For example usage see grabber link:example_v4l2.html[examples].
  11
  12 Grabber API
  13 ~~~~~~~~~~~
  14
  15 The grabber API consist of structure with callbacks. Every grabber
  16 initialization yields pointer to this structure. Although is possible to call
  17 these pointers directly it's not recommended and everybody should rather use
  18 the inline functions instead.
  19
  20 The grabber API consist GP_Grabber structure and of several functions:
  21
  22 [source,c]
  23 -------------------------------------------------------------------------------
  24 typdef struct GP_Grabber {
  25         /*
  26          * Currently loaded frame.
  27          */
  28         GP_Pixmap *frame;
  29
  30         /*
  31          * Connection fd usable for select() or poll().
  32          *
  33          * Set to -1 if not available.
  34          */
  35         int fd;
  36
  37         /* ... */
  38 };
  39 -------------------------------------------------------------------------------
  40
  41 The frame is a pointer to currently loaded frame. Its content is undefined
  42 until you start the grabber with 'GP_GrabberStart()' and receive frame with
  43 'GP_GrabberPoll()'.
  44
  45 The 'fd' is a file descriptor suitable for select() or poll(). It's set to -1
  46 if there is none.
  47
  48
  49 [source,c]
  50 -------------------------------------------------------------------------------
  51 #include <grabbers/GP_Grabber.h>
  52 /* or */
  53 #include <GP.h>
  54
  55 void GP_GrabberExit(GP_Grabber *backend);
  56 -------------------------------------------------------------------------------
  57
  58 Exits the grabber, frees memory, unmaps memory mappings, closes file
  59 descriptors etc...
  60
  61 [source,c]
  62 -------------------------------------------------------------------------------
  63 #include <grabbers/GP_Grabber.h>
  64 /* or */
  65 #include <GP.h>
  66
  67 int GP_GrabberStart(struct GP_Grabber *self);
  68 -------------------------------------------------------------------------------
  69
  70 Starts a grabber. After calling this you can start retrieving frames with
  71 'GP_GrabberPoll()'.
  72
  73 Returns zero on success and non-zero on failure.
  74
  75 [source,c]
  76 -------------------------------------------------------------------------------
  77 #include <grabbers/GP_Grabber.h>
  78 /* or */
  79 #include <GP.h>
  80
  81 int GP_GrabberStop(struct GP_Grabber *self);
  82 -------------------------------------------------------------------------------
  83
  84 Stops a grabber. Call this when you doesn't need to receive frames but still
  85 plan to use the grabber later.
  86
  87 Returns zero on success and non-zero on failure.
  88
  89 [source,c]
  90 -------------------------------------------------------------------------------
  91 #include <grabbers/GP_Grabber.h>
  92 /* or */
  93 #include <GP.h>
  94
  95 int GP_GrabberPoll(struct GP_Grabber *self);
  96 -------------------------------------------------------------------------------
  97
  98 Once grabber is created you can call this function to receive a frame. If
  99 grabber 'fd' is not -1 it's preferable to call it when select() or poll()
 100 returns that data are available on the 'fd'.
 101
 102 This function returns non-zero if new frame was received and stored into the
 103 'frame' pixmap. Otherwise zero is returned.
 104
 105 Grabber Initializations
 106 ~~~~~~~~~~~~~~~~~~~~~~
 107
 108 [source,c]
 109 -------------------------------------------------------------------------------
 110 #include <grabbers/GP_V4L2.h>
 111 /* or */
 112 #include <GP.h>
 113
 114 struct GP_Grabber *GP_GrabberV4L2Init(const char *device,
 115                                       unsigned int preferred_width,
 116                                       unsigned int preferred_height);
 117 -------------------------------------------------------------------------------
 118
 119 Opens and initializes V4L2 device. The device is a path in +/dev+ filesystem
 120 the first V4L2 device in your system should be +/dev/video0+.
 121
 122 The height and width are preferred values, you will most likely get frame by
 123 that width and height, but the driver may return different values if chosen
 124 width and height are not supported.
 125
 126 Returns either pointer to the initialized grabber or, in case of failure,
 127 NULL and errno is set.
 128