AG_PIXMAP(3)

NAME
AG_Pixmap - agar pixmap display widget

SYNOPSIS

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

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

Multiple images may be associated with an AG_Pixmap instance. This allows animations to be displayed (i.e., by mapping the frames using AG_PixmapAddSurface() and calling AG_PixmapSetSurface() from an AG_Timer(3) callback or a separate thread).

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, const AG_Surface *src)

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

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

AG_Pixmap * AG_PixmapFromFile(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 AG_PixmapFromSurface() function creates a new AG_Pixmap widget displaying a copy of the specified surface. A pixel-format conversion is performed if necessary. If the src argument is NULL, an empty surface is displayed. The AG_PixmapFromSurfaceScaled() variant resizes the image to the given dimensions.

The AG_PixmapFromSurfaceNODUP() variant uses the specified surface without making a copy. The provided surface must remain valid as long as the widget exists, and it must be in a format that can be displayed directly (such as agSurfaceFmt).

The AG_PixmapFromFile() function loads a surface from the image file at path (image type is autodetected).

AG_PixmapFromTexture() may be used to display an active hardware texture. lod specifies the level-of-detail of the texture (level 0 is the base image level). If OpenGL support is not available, an error is returned.

CHANGING SURFACES
int AG_PixmapAddSurface(AG_Pixmap *pixmap, const AG_Surface *surface)

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

int AG_PixmapAddSurfaceFromFile(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_PixmapUpdateSurface(AG_Pixmap *pixmap, int surface_name)

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

The AG_PixmapAddSurface() functions maps a copy of the specified surface. AG_PixmapAddSurfaceScaled() maps a copy of the given surface, resized to width by height pixels. AG_PixmapAddSurfaceFromFile() maps a surface obtained from an image file (format is autodetected).

AG_PixmapSetSurface() changes the currently displayed surface (see n in STRUCTURE DATA). The argument should be the handle of one of the surfaces previously mapped with AG_PixmapAddSurface().

The AG_PixmapReplaceSurface() routine replaces the contents of the specified surface mapping.

If the contents of a currently mapped surface are directly modified, AG_PixmapUpdateSurface() should be called. This routine may or may not be a no-op depending on the graphics mode.

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

EVENTS
The AG_Pixmap widget does not generate any event.

STRUCTURE DATA
For the AG_Pixmap object:

int n
    Handle of currently displayed surface (-1 = none).

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 some image files:

    AG_PixmapFromFile(sv, 0, "foo.png");
    AG_PixmapFromFile(sv, 0, "bar.jpg");

The following code fragment loads 30 frames in JPEG format:

    char path[AG_FILENAME_MAX];
    AG_Pixmap *px;
    int frames[30];
    int i;
    px = AG_PixmapNew(win, 0, 320,240);
    for (i = 0; i < 30; i++) {
    	AG_Snprintf(path, sizeof(path), "%08d.jpg", i);
    	frames[i] = AG_PixmapAddSurfaceFromFile(px, path);
    }

Running from a separate thread, the following code fragment would play back the animation:

    for (i = 0; i < 30; i++) {
    	AG_PixmapSetSurface(px, frames[i]);
    	AG_Delay(10);
    }

SEE ALSO
AG_Fixed(3), AG_Intro(3), AG_Scrollview(3), AG_Surface(3), AG_View(3), AG_Widget(3), AG_Window(3)

See tests/fixedres.c in the Agar source distribution.

HISTORY
The AG_Pixmap widget first appeared in Agar 1.0.