Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AG_DRIVER(3)		 BSD Library Functions Manual		  AG_DRIVER(3)

     AG_Driver -- agar low-level driver	interface

     #include <agar/core.h>
     #include <agar/gui.h>

     In	Agar, low-level	graphics rendering, event processing and window	man-
     agement is	handled	by modular "drivers".  A simple	class registration in-
     terface allows Agar to be "ported"	to new platforms, environments and
     graphics systems.	In a manner similar to Agar widgets, new Agar "driv-
     ers" may be implemented as	part of	an application,	without	need for
     changing the Agar source code itself.

     For the list of drivers included in the Agar distribution,	see the
     AG_InitGraphics(3)	manual page, under "AVAILABLE DRIVERS".

     The interface differs based on whether an underlying window system	is
     available.	 All drivers are a subclass of AG_Driver.  The AG_DriverSw
     subclass (for "single-window") is used by drivers that do not interface
     with an underlying	window system.	For example, the "sdlfb" and "sdlgl"
     drivers use the SDL 1.x API, and are therefore limited to a single	window
     as	far as the native window system	is concerned).	A dumb framebuffer
     used in an	embedded device	would also use the AG_DriverSw subclass.

     The AG_DriverMw subclass (for "multiple-window") is used by drivers that
     do	interface with an underlying window system.  In	a multiple-window en-
     vironment,	each Agar window (e.g.,	each window created by
     AG_WindowNew(3)) is associated with a "native" window.  For example, the
     "glx" driver uses the GLX API to create an	accelerated rendering context,
     and also uses the Xlib API	to manage windows.

     The part of the AG_Driver API that	deals with low-level event processing
     is	of particular importance to applications using custom event loops (see
     AG_CustomEventLoop(3) for an example).  It	is possible, in	a driver-inde-
     pendent fashion, for an application to catch and process low-level	events
     (see below).

     AG_Driver * AG_DriverOpen(AG_DriverClass *dc)

     void AG_DriverClose(AG_Driver *drv)

     void AG_ListDriverNames(char *buf,	size_t buf_len)

     int AG_UsingGL(AG_Driver *drv)

     int AG_UsingSDL(AG_Driver *drv)

     int AG_GetDisplaySize(AG_Driver *drv, Uint	*w, Uint *h)

     The AG_DriverOpen() function creates a new	instance of a driver class, as
     described by dc (see section below).  AG_DriverClose() destroys a driver
     instance.	These two functions are	seldom used directly, since they are
     called internally from either AG_InitGraphics(3) or AG_WindowNew(3) in
     the case of multiple-window drivers (which	use one	driver instance	per

     The AG_ListDriverNames() returns a	space-separated	list of	available
     drivers for the current platform, into the	specified buffer buf of	size

     The AG_UsingGL() and AG_UsingSDL()	functions return 1 if Agar is using
     OpenGL or SDL, respectively.  drv is a pointer to the driver instance (or
     if	NULL, use the default driver instance).

     The AG_GetDisplaySize() function obtains the maximum available display
     area in pixels.  On success, the dimensions are returned into the w and h
     arguments,	and the	function returns 0.  drv is a pointer to the driver
     instance (or if NULL, use the default driver instance).

     The AG_DriverClass	structure inherits from	the base AG_Object(3) class,
     and is defined as follows:

     typedef struct ag_driver_class {
	     struct ag_object_class _inherit;
	     const char	*name;			     /*	Short name */
	     enum ag_driver_type type;		     /*	Driver type */
	     enum ag_driver_wm_type wm;		     /*	Window manager type */
	     Uint flags;			     /*	Flags; see below */

	     /*	Initialization */
	     int  (*open)(void *drv, const char	*spec);
	     void (*close)(void	*drv);
	     int  (*getDisplaySize)(Uint *w, Uint *h);

	     /*	Event processing */
	     void (*beginEventProcessing)(void *drv);
	     int  (*pendingEvents)(void	*drv);
	     int  (*getNextEvent)(void *drv, AG_DriverEvent *dev);
	     int  (*processEvent)(void *drv, AG_DriverEvent *dev);
	     void (*genericEventLoop)(void *drv);
	     void (*endEventProcessing)(void *drv);
	     void (*terminate)(void);

	     /*	Rendering and texture management */
	     void (*beginRendering)(void *drv);
	     void (*renderWindow)(AG_Window *w);
	     void (*endRendering)(void *drv);
	     void (*fillRect)(void *drv, AG_Rect r, AG_Color c);
	     void (*updateRegion)(void *drv, AG_Rect r);
	     void (*uploadTexture)(void	*drv, Uint *texID, AG_Surface *su,
				   AG_TexCoord *tc);
	     int  (*updateTexture)(void	*drv, Uint texID, AG_Surface *su,
				   AG_TexCoord *tc);
	     void (*deleteTexture)(void	*drv, Uint texID);
	     int (*setRefreshRate)(void	*drv, int fps);

	     /*	Clipping and blending control (rendering context) */
	     void (*pushClipRect)(void *drv, AG_Rect r);
	     void (*popClipRect)(void *drv);
	     void (*pushBlendingMode)(void *drv, AG_BlendFn sFn,
				      AG_BlendFn dFn);
	     void (*popBlendingMode)(void *drv);

	     /*	Hardware cursor	interface */
	     AG_Cursor *(*createCursor)(void *drv, Uint	w, Uint	h,
					const Uint8 *data, const Uint8 *mask,
					int xHot, int yHot);
	     void (*freeCursor)(void *drv, AG_Cursor *curs);
	     int  (*setCursor)(void *drv, AG_Cursor *curs);
	     void (*unsetCursor)(void *drv);
	     int  (*getCursorVisibility)(void *drv);
	     void (*setCursorVisibility)(void *drv, int	flag);

	     /*	Widget surface operations (rendering context) */
	     void (*blitSurface)(void *drv, AG_Widget *wid,
				 AG_Surface *s,	int x, int y);
	     void (*blitSurfaceFrom)(void *drv,	AG_Widget *wid,	AG_Widget
				     *widSrc, int s, AG_Rect *r, int x,	int y);
	     void (*blitSurfaceGL)(void	*drv, AG_Widget	*wid, AG_Surface *s,
				   float w, float h);
	     void (*blitSurfaceFromGL)(void *drv, AG_Widget *wid, int s,
				       float w,	float h);
	     void (*blitSurfaceFlippedGL)(void *drv, AG_Widget *wid, int s,
					  float	w, float h);
	     void (*backupSurfaces)(void *drv, AG_Widget *wid);
	     void (*restoreSurfaces)(void *drv,	AG_Widget *wid);
	     int  (*renderToSurface)(void *drv,	AG_Widget *wid,
				     AG_Surface	**su);

	     /*	Rendering operations (rendering	context) */
	     void (*putPixel)(void *drv, int x,	int y, AG_Color	c);
	     void (*putPixel32)(void *drv, int x, int y, Uint32	c);
	     void (*putPixelRGB)(void *drv, int	x, int y, Uint8	r, Uint8 g,
				 Uint8 b);
	     void (*blendPixel)(void *drv, int x, int y, AG_Color c,
				AG_BlendFn sFn,	AG_BlendFn dFn);
	     void (*drawLine)(void *drv, int x1, int y1, int x2, int y2,
			      AG_Color C);
	     void (*drawLineH)(void *drv, int x1, int x2, int y, AG_Color C);
	     void (*drawLineV)(void *drv, int x, int y1, int y2, AG_Color C);
	     void (*drawLineBlended)(void *drv,	int x1,	int y1,	int x2,	int y2,
				     AG_Color C, AG_BlendFn sFn,
				     AG_BlendFn	dFn);
	     void (*drawArrowUp)(void *drv, int	x, int y, int h, AG_Color C[2]);
	     void (*drawArrowDown)(void	*drv, int x, int y, int	h,
				   AG_Color C[2]);
	     void (*drawArrowLeft)(void	*drv, int x, int y, int	h,
				   AG_Color C[2]);
	     void (*drawArrowRight)(void *drv, int x, int y, int h,
				    AG_Color C[2]);
	     void (*drawBoxRounded)(void *drv, AG_Rect r, int z, int rad,
				    AG_Color C[3]);
	     void (*drawBoxRoundedTop)(void *drv, AG_Rect r, int z, int	rad,
				       AG_Color	C[3]);
	     void (*drawCircle)(void *drv, int x, int y, int r,	AG_Color C);
	     void (*drawCircle2)(void *drv, int	x, int y, int r, AG_Color C);
	     void (*drawRectFilled)(void *drv, AG_Rect r, AG_Color C);
	     void (*drawRectBlended)(void *drv,	AG_Rect	r, AG_Color C,
				     AG_BlendFn	sFn, AG_BlendFn	dFn);
	     void (*drawRectDithered)(void *drv, AG_Rect r, AG_Color C);
	     void (*updateGlyph)(void *drv, AG_Glyph *gl);
	     void (*drawGlyph)(void *drv, const	AG_Glyph *gl, int x, int y);

	     /*	Display	list management	(GL driver specific) */
	     void (*deleteList)(void *drv, Uint	listID);
     } AG_DriverClass;

     The type field should be set to AG_FRAMEBUFFER for	dumb-framebuffer draw-
     ing, or AG_VECTOR for vector-based	drawing	such as	OpenGL.

     The wm field may be set to	AG_WM_SINGLE for single-window drivers,	or
     AG_WM_MULTIPLE for	multiple-window	drivers.

     Acceptable	values for the flags field include:
     AG_DRIVER_OPENGL	  OpenGL calls are supported.
     AG_DRIVER_SDL	  SDL 1.x calls	are supported.
     AG_DRIVER_TEXTURES	  Texture management operations	are supported.

     The open()	method is invoked to initialize	a new driver instance.	open()
     is	expected to initialize the mouse and kbd fields	of AG_Driver (see
     AG_MouseNew(3), AG_KeyboardNew(3)).  Return 0 on success and -1 on	fail-

     The close() method	is invoked to destroy a	driver instance.  It is	ex-
     pected to destroy the mouse and kbd fields	of AG_Driver.

     The getDisplaySize() operation should return the total display size
     available,	in pixels, into	w and h.  For single-window drivers, this is
     the size of the display available to Agar.	 For multiple-window drivers,
     this is the total size of the desktop (if multiple	workspaces are sup-
     ported, it	should be limited to the size of a single workspace in pix-
     els).  This operation should return 0 on success and -1 on	failure.

     The beginEventProcessing()	callback is invoked before event processing
     begins.  Most drivers will	not need to do anything	here.

     pendingEvents() returns a non-zero	value if there are events waiting to
     be	processed (see AG_PendingEvents()).

     getNextEvent() retrieves and remove the next event	from the queue (see

     processEvent() processes the event	described by dev (see

     The genericEventLoop() method is obsolete as of Agar-1.5 (see

     The endEventProcessing() callback is invoked after	event processing is
     done.  For	most drivers, there is nothing to do here.

     The terminate() operation is obsolete as of Agar-1.5 (see

     The beginRendering() and endRendering() operations	are invoked by
     AG_BeginRendering(3) and AG_EndRendering(3) to prepare for	rendering of
     GUI elements.

     The renderWindow()	operation renders an Agar window.  Usually, it will
     simply invoke AG_WidgetDraw(3) on win.  Framebuffer drivers may also want
     to	update video regions from here.

     The fillRect() operation is expected to fill a rectangle r	with color c.

     The updateRegion()	operation, usually specific to framebuffer drivers, is
     expected to update	a region of video memory represented by	r.

     uploadTexture(), updateTexture() and deleteTexture() are specific to
     drivers with texture management facilities.  uploadTexture() creates a
     texture from an AG_Surface(3), returning the computed texture coordi-
     nates.  updateTexture() is	expected to update an existing texture from a
     recently modified surface.	 deleteTexture() arranges for the specified
     texture to	be deleted as soon as possible.

     The setRefreshRate() operation is invoked by AG_SetRefreshRate(3),	to
     configure a fixed refresh rate, as	a driver-specific hint that can	be ig-

     pushClipRect() should create a clipping rectangle over r.	If a clipping
     rectangle is already in effect, it	should be saved	on a stack.
     popClipRect() pops	the last clipping rectangle off	the stack.

     pushBlendingMode()	should configure an alpha blending mode	(see
     AG_BlendFn(3)).  If a blending mode is already set, it should be saved on
     a stack.  popBlendingMode() pops the last blending	mode off the stack.

     The following operations are optional and provide Agar with access	over
     hardware cursors.	See AG_Cursor(3) for details on	the Agar cursor	con-
     trol interface.

     The createCursor()	operation creates a hardware cursor from the bitmap
     data data and transparency	mask mask.  The	hotspot	coordinates are	given
     in	xHot, yHot.  If	a hardware cursor cannot be allocated, the call	should
     return NULL.  freeCursor()	destroys any hardware cursor corresponding to
     the given AG_Cursor structure.

     The setCursor() operation changes the current cursor to the specified
     cursor, returning 0 on success or -1 on failure.  unsetCursor() reverts
     to	the default cursor.

     The getCursorVisibility() and setCursorVisibility() routines retrieve and
     set the cursor visibility flag.

     The following operations form the backend of the AG_Widget(3) surface op-
     erations such as AG_WidgetBlitFrom(3).  They all accept a AG_Widget argu-
     ment, and coordinate arguments are	always with respect to the widget's
     local coordinate system.

     The blitSurface() operation implements AG_WidgetBlit(3), which performs
     (or emulates) a surface blit from the given AG_Surface(3),	to target co-
     ordinates x, y.  The blitSurfaceFrom() variant of this operation imple-
     ments AG_WidgetBlitFrom(3), which uses a registered widget	surface	as
     source, and is generally much more	amenable to hardware acceleration than

     The blitSurfaceGL() and blitSurfaceFromGL() variants are specific to
     OpenGL drivers.  Instead of accepting an explicit source or destination
     rectangle parameter, they rely on the current transformation matrix being
     set accordingly.  blitSurfaceFlippedGL() reverses the order of the	rows
     in	the image.

     The backupSurfaces() operation should create a software backup of all
     surfaces registered under the given widget.  restoreSurfaces() restores a
     widget's surfaces from backup.  These operations are needed with OpenGL
     on	some platforms,	where a	window resize may result in a loss of OpenGL
     context data.

     The renderToSurface() operation renders a widget to a newly allocated
     AG_Surface(3), returned into the su argument.  The	function should	return
     0 on success or -1	on failure.

     putPixel(), putPixel32() and putPixelRGB()	writes a pixel of specified
     color at coordinates x, y.	 blendPixelRGB() performs blending against the
     target pixel at x,	y.  See	AG_BlendFn(3) for acceptable sFn and dFn val-

     The drawLine() routine renders a line of color C from endpoint x1,	y1 to
     endpoint x2, y2.  The drawLineH() operation renders a horizontal line,
     and drawLineV() renders a vertical	line.  drawLineBlended() renders a
     line with transparency (see AG_BlendFn(3)).

     drawArrowUp(), drawArrowDown(), drawArrowLeft() and drawArrowRight() ren-
     der an arrow of length h, at coordinates x, y.

     drawBoxRounded() renders a	3D-style box of	depth z, with corners rounded
     to	radius rad.  The drawBoxRoundedTop() variant only rounds the two top

     The drawCircle() operation	renders	a circle of radius r, centered around
     x,	y.  The	drawCircle2() variant adds a 3D-style effect.

     The drawRectFilled() operation fills the target rectangle r with the
     given color drawRectBlended() renders a filled rectangle with transpar-
     ency (see AG_BlendFn(3)).	drawRectDithered() renders a filled rectangle
     with ditering effect (commonly used to illustrate "disabled" GUI con-

     The updateGlyph() operation ensures that the specified font glyph (see
     AG_Text(3)) is ready to be	rendered.  OpenGL drivers, for example,	can
     use this operation	to upload a rendered version of	the glyph to the tex-
     ture hardware.  The drawGlyph() operation renders a given font glyph at
     target coordinates	x, y.  The target point	will correspond	to the top
     left corner of the	rendered glyph.

     The deleteList() operation	arranges for the specified display list	to be
     deleted as	soon as	possible (typically in the endRendering() routine).

     int AG_PendingEvents(AG_Driver *drv)

     int AG_GetNextEvent(AG_Driver *drv, AG_DriverEvent	*dev)

     int AG_ProcessEvent(AG_Driver *drv, AG_DriverEvent	*dev)

     /*	Requires Agar compiled --with-sdl */
     int AG_SDL_TranslateEvent(AG_Driver *drv, const SDL_Event *ev,
     AG_DriverEvent *dev)

     void AG_WindowProcessQueued(void)

     Low-level driver events are represented by	the AG_DriverEvent structure,
     which provides the	public members type and	win.  The win member is	a
     pointer to	the corresponding AG_Window(3) (for single-window drivers, win
     is	always NULL).  The type	field is an enum that can take on the values:

     AG_DRIVER_MOUSE_MOTION	   Mouse cursor	has moved to coordinates
     AG_DRIVER_MOUSE_BUTTON_UP	   Mouse button	has been pressed or released
				   at coordinates data.button.{x,y}.  The but-
				   ton index is	passed as data.button.which.
     AG_DRIVER_MOUSE_LEAVE	   The mouse cursor has	entered	or left	the
				   window area.	 These events are specific to
				   multiple-window drivers.
     AG_DRIVER_FOCUS_OUT	   Application focus has been gained or	lost.
				   These events	are specific to	multiple-win-
				   dow drivers.
     AG_DRIVER_KEY_UP		   A key has been pressed or released.	The
				   keysym (see AG_KeySym(3)) is	passed as
				   data.key.ks.	 A 32-bit Unicode (UCS-4) rep-
				   resentation of the corresponding character,
				   if any, is passed as	data.key.ucs.
     AG_DRIVER_EXPOSE		   The underlying graphics system is request-
				   ing a refresh of the	video display.
     AG_DRIVER_VIDEORESIZE	   The application window has been resized to
				   data.videoresize.{w,h}.  Some drivers may
				   also	raise this event when the window is
     AG_DRIVER_CLOSE		   The user has	requested that a window	be
				   closed.  For	multiple-window	drivers, the
				   default behavior is to post a
				   `window-close' event	to the corresponding
				   Agar	window.	 For single-window drivers,
				   the application is usually terminated as a

     The AG_PendingEvents() function returns 1 if there	are events waiting to
     be	processed, or 0	if the event queue is empty.

     AG_GetNextEvent() retrieves and removes the next event on the queue, ini-
     tializing the structure pointed by	dev with its contents.
     AG_GetNextEvent() returns 1 if the	event has been successfully retrieved
     into dev.	The function returns 0 if the event was	dequeued (and no fur-
     ther processing is	required), or -1 if an error occured.

     AG_ProcessEvent() processes the event pointed to by dev in	the default
     manner.  The call returns 1 if the	event was successfully,	0 if Agar has
     ignored the event entirely, or -1 if an error occured.

     The AG_SDL_TranslateEvent() function translates a SDL_Event(3) structure
     to	an Agar	AG_DriverEvent().  This	function is only available if Agar was
     compiled with SDL support.

     The drv argument AG_PendingEvents(), AG_GetNextEvent(), AG_ProcessEvent()
     and AG_SDL_TranslateEvent() specify a driver instance.  This is useful
     for applications using multiple drivers concurrently.  In most cases,
     this argument should be passed as NULL, so	the default driver instance
     will be used.

     The following code	fragment implements a basic event loop.	 It retrieves
     pending events, examines them, and	forwards them to Agar for processing:

	   AG_DriverEvent ev;

	   while (AG_PendingEvents(NULL) > 0) {
		   if (AG_GetNextEvent(NULL, &ev)) {
			   switch (ev.type) {
				   printf("Click at %d,%d\n",
			   case	AG_DRIVER_KEY_DOWN:
				   printf("Key pressed:	%d\n",
			   if (AG_ProcessEvent(NULL, &ev) == -1)

     AG_GL(3), AG_InitGraphics(3), AG_Intro(3),	AG_Widget(3), AG_Window(3)

     The AG_Driver interface first appeared in Agar 1.4.0.

BSD				March 22, 2010				   BSD


Want to link to this manual page? Use this URL:

home | help