NAME

SYNOPSIS

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

DESCRIPTION

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 environment, 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-independent fashion, for an application to catch and process low-level events (see below).

DRIVER INTERFACE

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 window).

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

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).

DRIVER CLASS STRUCTURE

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 drawing, 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 failure.

The close() method is invoked to destroy a driver instance. It is expected 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 supported, it should be limited to the size of a single workspace in pixels). 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 AG_GetNextEvent()).

processEvent() processes the event described by dev (see AG_ProcessEvent()).

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

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 AG_Terminate(3)).

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 coordinates. 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 ignored.

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 control 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 operations such as AG_WidgetBlitFrom(3). They all accept a AG_Widget argument, 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 coordinates x, y. The blitSurfaceFrom() variant of this operation implements AG_WidgetBlitFrom(3), which uses a registered widget surface as source, and is generally much more amenable to hardware acceleration than blitSurface().

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 values.

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() render 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 corners.

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 transparency (see AG_BlendFn(3)). drawRectDithered() renders a filled rectangle with ditering effect (commonly used to illustrate "disabled" GUI controls).

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 texture 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).

EVENT PROCESSING

int
AG_GetNextEvent(AG_Driver *drv, AG_DriverEvent *dev);

int
AG_ProcessEvent(AG_Driver *drv, AG_DriverEvent *dev);

/* Requires Agar compiled --with-sdl */

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 data.motion.{x,y}.

AG_DRIVER_MOUSE_BUTTON_DOWN

 

AG_DRIVER_MOUSE_BUTTON_UP

Mouse button has been pressed or released at coordinates data.button.{x,y}. The button index is passed as data.button.which.

AG_DRIVER_MOUSE_ENTER

 

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_IN

 

AG_DRIVER_FOCUS_OUT

Application focus has been gained or lost. These events are specific to multiple-window drivers.

AG_DRIVER_KEY_DOWN

 

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) representation of the corresponding character, if any, is passed as data.key.ucs.

AG_DRIVER_EXPOSE

The underlying graphics system is requesting 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 moved.

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 result.

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, initializing 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 further 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.

EXAMPLES

AG_DriverEvent ev;

while (AG_PendingEvents(NULL) > 0) {
	if (AG_GetNextEvent(NULL, &ev)) {
		switch (ev.type) {
		case AG_DRIVER_MOUSE_BUTTON_DOWN:
			printf("Click at %d,%d\n",
			    dev.data.button.x,
			    dev.data.button.y);
			break;
		case AG_DRIVER_KEY_DOWN:
			printf("Key pressed: %d\n",
			    (int)dev.data.key.ks);
			break;
		default:
			break;
		}
		if (AG_ProcessEvent(NULL, &ev) == -1)
			break;
	}
}

SEE ALSO

HISTORY