This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project gfxprim.git. The branch, master has been updated via b7b1aa5e558261c0787fad6e924969625cd465ce (commit) from 0f6d751635c094c8857706c11538637cda8dfc6f (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://repo.or.cz/w/gfxprim.git/commit/b7b1aa5e558261c0787fad6e924969625cd46... commit b7b1aa5e558261c0787fad6e924969625cd465ce Author: Cyril Hrubis <metan@ucw.cz> Date: Fri Jul 6 14:50:23 2012 +0200 doc: Add grabbers docs + spellcheck in API. diff --git a/doc/Makefile b/doc/Makefile index 3fdfaad..7eb952d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,7 +1,8 @@ all: api.html examples.html api.html: general.txt api.txt context.txt loaders.txt filters.txt - basic_types.txt drawing_api.txt backends.txt gamma.txt + basic_types.txt drawing_api.txt backends.txt gamma.txt + grabbers.txt asciidoc -a toc api.txt examples.html: examples.txt ../demos/c_simple/*.c ../demos/py_simple/*.py diff --git a/doc/api.txt b/doc/api.txt index 402c6dd..37979b4 100644 --- a/doc/api.txt +++ b/doc/api.txt @@ -10,3 +10,4 @@ include::drawing_api.txt[] include::filters.txt[] include::loaders.txt[] include::backends.txt[] +include::grabbers.txt[] diff --git a/doc/backends.txt b/doc/backends.txt index ecd3468..66728f7 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -245,3 +245,4 @@ returned. If backend size already matches w and h, nothing is done. Note that backend->context pointer may change upon calling this function and at least backend->context->pixels pointer will change. + diff --git a/doc/grabbers.txt b/doc/grabbers.txt new file mode 100644 index 0000000..571cc06 --- /dev/null +++ b/doc/grabbers.txt @@ -0,0 +1,126 @@ +Grabbers +-------- + +Grabber is an abstraction for a device whose output is a stream of images. + +There is currently V4L2 driver that implements a grabber. + +To link against grabbers use +-lGP_grabbers+ or better ++`gfxprim-config --libs-grabbers`+ in your linker flags. + +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 frame. + */ + GP_Context *frame; + + /* + * Connection fd usable for select() or poll(). + * + * Set to -1 if not available. + */ + int fd; + + /* ... */ +}; +------------------------------------------------------------------------------- + +The frame is a pointer to currently loaded frame. Its content is undefined +until you start the grabber with 'GP_GrabberStart()'. + +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 <GP.h> + +void GP_GrabberExit(GP_Grabber *backend); +------------------------------------------------------------------------------- + +Exits the grabber, frees memory, unmaps memory mappings, closes file +descriptors etc... + +Returns zero on success and non-zero on failure. + +[source,c] +------------------------------------------------------------------------------- +#include <grabbers/GP_Grabber.h> +/* or */ +#include <GP.h> + +int GP_GrabberStart(struct GP_Grabber *self); +------------------------------------------------------------------------------- + +Starts a grabber. After calling this calling you can start retrieving frames +with 'GP_GrabberPoll()'. + +Returns zero on success and non-zero on failure. + +[source,c] +------------------------------------------------------------------------------- +#include <grabbers/GP_Grabber.h> +/* or */ +#include <GP.h> + +int GP_GrabberStop(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. + + +[source,c] +------------------------------------------------------------------------------- +#include <grabbers/GP_Grabber.h> +/* or */ +#include <GP.h> + +int GP_GrabberPoll(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' context. Otherwise zero is returned. + +Grabber Initializations +~~~~~~~~~~~~~~~~~~~~~~ + +[source,c] +------------------------------------------------------------------------------- +#include <grabbers/GP_V4L2.h> +/* or */ +#include <GP.h> + +struct GP_Grabber *GP_GrabberV4L2Init(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 filled. diff --git a/include/grabbers/GP_V4L2.h b/include/grabbers/GP_V4L2.h index aa6bf08..9b7b043 100644 --- a/include/grabbers/GP_V4L2.h +++ b/include/grabbers/GP_V4L2.h @@ -32,7 +32,7 @@ struct GP_Grabber; * fixed image size. */ struct GP_Grabber *GP_GrabberV4L2Init(const char *device, - unsigned int prefered_width, - unsigned int prefered_height); + unsigned int preferred_width, + unsigned int preferred_height); #endif /* GP_GRABBERS_V4L2_H */ diff --git a/libs/grabbers/GP_V4L2.c b/libs/grabbers/GP_V4L2.c index fa8a795..4a00e51 100644 --- a/libs/grabbers/GP_V4L2.c +++ b/libs/grabbers/GP_V4L2.c @@ -233,8 +233,8 @@ static int v4l2_stop(struct GP_Grabber *self) } struct GP_Grabber *GP_GrabberV4L2Init(const char *device, - unsigned int prefered_width, - unsigned int prefered_height) + unsigned int preferred_width, + unsigned int preferred_height) { int fd, i, err; int mode = 0; @@ -308,8 +308,8 @@ struct GP_Grabber *GP_GrabberV4L2Init(const char *device, memset(&fmt, 0, sizeof(fmt)); fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - fmt.fmt.pix.width = prefered_width; - fmt.fmt.pix.height = prefered_height; + fmt.fmt.pix.width = preferred_width; + fmt.fmt.pix.height = preferred_height; fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; @@ -422,8 +422,8 @@ err: #else struct GP_Grabber *GP_GrabberV4L2Init(const char GP_UNUSED(*device), - unsigned int GP_UNUSED(prefered_width), - unsigned int GP_UNUSED(prefered_height)) + unsigned int GP_UNUSED(preferred_width), + unsigned int GP_UNUSED(preferred_height)) { GP_WARN("V4L2 support not compiled in."); ----------------------------------------------------------------------- Summary of changes: doc/Makefile | 3 +- doc/api.txt | 1 + doc/backends.txt | 1 + doc/grabbers.txt | 126 ++++++++++++++++++++++++++++++++++++++++++++ include/grabbers/GP_V4L2.h | 4 +- libs/grabbers/GP_V4L2.c | 12 ++-- 6 files changed, 138 insertions(+), 9 deletions(-) create mode 100644 doc/grabbers.txt repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos@gmail.com if you want to unsubscribe, or site admin admin@repo.or.cz if you receive no reply. -- gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")