Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

The AG_Pixmap widget displays an image in pixmap format. It is frequently used along with AG_Fixed(3) to display interface decorations.

In OpenGL mode, the image surfaces are uploaded to the texture unit as they are mapped or updated.

Small animations can be efficiently displayed by mapping one surface per frame and invoking AG_PixmapSetSurface() from a timer with AG_Timeout(3).

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget(3)-> AG_Pixmap.

INITIALIZATION

AG_Pixmap * AG_PixmapNew (AG_Widget *parent, Uint flags, Uint width, Uint height)

AG_Pixmap * AG_PixmapFromSurface (AG_Widget *parent, Uint flags, AG_Surface *src)

AG_Pixmap * AG_PixmapFromSurfaceCopy (AG_Widget *parent, Uint flags, AG_Surface *src)

AG_Pixmap * AG_PixmapFromSurfaceScaled (AG_Widget *parent, Uint flags, AG_Surface *src, int width, int height)

AG_Pixmap * AG_PixmapFromBMP (AG_Widget *parent, Uint flags, const char *path)

AG_Pixmap * AG_PixmapFromTexture (AG_Widget *parent, Uint flags, GLuint texture, int lod)

The AG_PixmapNew() function creates a new AG_Pixmap not linked to any surface. The initial geometry of the widget is defined by the width and height parameters. Acceptable flags include:

AG_PIXMAP_RESCALE	Rescale image to fit widget size.
AG_PIXMAP_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_PIXMAP_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_PIXMAP_EXPAND	Shorthand for AG_PIXMAP_HFILL\|AG_PIXMAP_VFILL.

The following functions create a new AG_Pixmap with an image obtained from the given source. When using these constructors, the geometry of the widget is set to that of the source image.

AG_PixmapFromSurface() maps an existing AG_Surface(3) to surface 0. The surface must remain valid until the widget is destroyed. The AG_PixmapFromSurfaceCopy() variant instead creates and manages a copy of the surface. AG_PixmapFromSurfaceScaled() uses rescaled copy of the surface.

The AG_PixmapFromBMP() variant loads a surface from the bmp file at path.

The AG_PixmapFromTexture() function copies the surface from an existing GL texture. lod specifies the level-of-detail of the texture (level 0 is the base image level). This function is only available if Agar was compiled with OpenGL support.

CHANGING SURFACES

int AG_PixmapAddSurface (AG_Pixmap *pixmap, AG_Surface *surface)

int AG_PixmapAddSurfaceCopy (AG_Pixmap *pixmap, AG_Surface *surface)

int AG_PixmapAddSurfaceScaled (AG_Pixmap *pixmap, AG_Surface *surface, int width, int height)

int AG_PixmapAddSurfaceFromBMP (AG_Pixmap *pixmap, const char *path)

void AG_PixmapSetSurface (AG_Pixmap *pixmap, int surface_name)

void AG_PixmapReplaceSurface (AG_Pixmap *pixmap, int surface_name, AG_Surface *surfaceNew)

void AG_PixmapReplaceCurrentSurface (AG_Pixmap *pixmap, AG_Surface *surfaceNew)

void AG_PixmapReplaceSurfaceScaled (AG_Pixmap *pixmap, int surface_name, AG_Surface *surfaceNew, Uint width, Uint height)

void AG_PixmapReplaceCurrentSurfaceScaled (AG_Pixmap *pixmap, AG_Surface *surfaceNew, Uint width, Uint height)

void AG_PixmapUpdateSurface (AG_Pixmap *pixmap, int surface_name)

void AG_PixmapUpdateCurrentSurface (AG_Pixmap *pixmap)

void AG_PixmapSetCoords (AG_Pixmap *pixmap, int s, int t)

The AG_Pixmap widget can map multiple surfaces and switch between them. To add a new surface, use AG_PixmapAddSurface(), AG_PixmapAddSurfaceCopy(), AG_PixmapAddSurfaceScaled() or AG_PixmapAddSurfaceFromBMP().

AG_PixmapSetSurface() changes the currently visible surface to another surface that has been previously mapped with AG_PixmapAddSurface*(). To replace an existing mapped surface, use AG_PixmapReplaceSurface() or AG_PixmapReplaceSurfaceScaled() with the name of the surface.

If you need to modify the contents of a previously mapped surface, it is necessary to call AG_PixmapUpdateSurface() afterwards. It has no effect in direct video mode, but it causes the texture to be re-uploaded to the graphics hardware in OpenGL mode.

The AG_PixmapReplaceCurrentSurface(), AG_PixmapReplaceCurrentSurfaceScaled() and AG_PixmapUpdateCurrentSurface() variants operate on the currently selected (visible) surface.

The AG_PixmapSetCoords() function changes the source coordinates of the active surface. The default is [0,0].

EVENTS

The AG_Pixmap widget neither reacts to nor generates any event.

STRUCTURE DATA

For the AG_Pixmap object:

int s, t

Source surface coordinates. Can be set using AG_PixmapSetCoords().

EXAMPLES

The following code fragment displays an existing AG_Surface(3). It packs AG_Pixmap in a AG_Scrollview(3) widget, allowing the user to pan the view:

AG_Scrollview *sv;
AG_Pixmap *px;
sv = AG_ScrollviewNew(window, AG_SCROLLVIEW_BY_MOUSE);
AG_Expand(sv);
px = AG_PixmapFromSurface(sv, 0, mySurface);

The following code fragment displays the contents of an image in bmp format. It uses AG_PIXMAP_RESCALE to scale the image to fit the widget geometry:

AG_Surface *s;
AG_Pixmap *px;
s = AG_SurfaceFromBMP("foo.bmp");
px = AG_PixmapFromSurface(sv, AG_PIXMAP_RESCALE, s);

HISTORY

The AG_Pixmap widget first appeared in Agar 1.0.