.\" Copyright (c) 2006-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_PIXMAP 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Pixmap
.Nd agar pixmap display widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(/widgets/AG_Pixmap.png, "An AG_Pixmap widget")
The
.Nm
widget displays an image in pixmap format.
It is commonly used along with
.Xr AG_Fixed 3
to display interface decorations.
.Pp
Multiple images may be associated with an
.Nm
instance.
Animation can be done by mapping frames with
.Fn AG_PixmapAddSurface
and calling
.Fn AG_PixmapSetSurface
from an
.Xr AG_Timer 3
callback or a separate thread.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Pixmap *"
.Fn AG_PixmapNew "AG_Widget *parent" "Uint flags" "Uint width" "Uint height"
.Pp
.Ft "AG_Pixmap *"
.Fn AG_PixmapFromSurface "AG_Widget *parent" "Uint flags" "const AG_Surface *src"
.Pp
.Ft "AG_Pixmap *"
.Fn AG_PixmapFromSurfaceScaled "AG_Widget *parent" "Uint flags" "const AG_Surface *src" "Uint width" "Uint height"
.Pp
.Ft "AG_Pixmap *"
.Fn AG_PixmapFromSurfaceNODUP "AG_Widget *parent" "Uint flags" "AG_Surface *src"
.Pp
.Ft "AG_Pixmap *"
.Fn AG_PixmapFromFile "AG_Widget *parent" "Uint flags" "const char *path"
.Pp
.Ft "AG_Pixmap *"
.Fn AG_PixmapFromTexture "AG_Widget *parent" "Uint flags" "GLuint texture" "int lod"
.Pp
.nr nS 0
The
.Fn AG_PixmapNew
function creates a new
.Nm
not linked to any surface.
The initial geometry of the widget is defined by the
.Fa width
and
.Fa height
parameters.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_PIXMAP_RESCALE "
.It AG_PIXMAP_RESCALE
Rescale image to fit widget size.
.It AG_PIXMAP_HFILL
Expand horizontally in parent container.
.It AG_PIXMAP_VFILL
Expand vertically in parent container.
.It AG_PIXMAP_EXPAND
Shorthand for
.Dv AG_PIXMAP_HFILL | AG_PIXMAP_VFILL .
.El
.Pp
The
.Fn AG_PixmapFromSurface
function creates a new
.Nm
widget displaying a copy of the specified surface.
A pixel-format conversion is performed if necessary.
If the
.Fa src
argument is NULL, an empty surface is displayed.
The
.Fn AG_PixmapFromSurfaceScaled
variant resizes the image to the given dimensions.
.Pp
The
.Fn 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
.Va agSurfaceFmt ) .
.Pp
The
.Fn AG_PixmapFromFile
function loads a surface from the image file at
.Fa path
(image type is autodetected).
.Pp
.Fn AG_PixmapFromTexture
may be used to display an active hardware texture.
.Fa 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.
.Sh CHANGING SURFACES
.nr nS 1
.Ft "int"
.Fn AG_PixmapAddSurface "AG_Pixmap *pixmap" "const AG_Surface *surface"
.Pp
.Ft "int"
.Fn AG_PixmapAddSurfaceScaled "AG_Pixmap *pixmap" "const AG_Surface *surface" "Uint width" "Uint height"
.Pp
.Ft "int"
.Fn AG_PixmapAddSurfaceFromFile "AG_Pixmap *pixmap" "const char *path"
.Pp
.Ft "void"
.Fn AG_PixmapSetSurface "AG_Pixmap *pixmap" "int surface_name"
.Pp
.Ft "AG_Surface *"
.Fn AG_PixmapGetSurface "AG_Pixmap *pixmap" "int surface_name"
.Pp
.Ft "void"
.Fn AG_PixmapReplaceSurface "AG_Pixmap *pixmap" "int surface_name" "AG_Surface *surfaceNew"
.Pp
.Ft "void"
.Fn AG_PixmapUpdateSurface "AG_Pixmap *pixmap" "int surface_name"
.Pp
.Ft "void"
.Fn AG_PixmapSizeHint "AG_Pixmap *pixmap" "int w" "int h"
.Pp
.Ft "void"
.Fn AG_PixmapSetCoords "AG_Pixmap *pixmap" "int s" "int t"
.Pp
.nr nS 0
The
.Fn AG_PixmapAddSurface
functions maps a copy of the specified surface.
.Fn AG_PixmapAddSurfaceScaled
maps a copy of the given surface, resized to
.Fa width
by
.Fa height
pixels.
.Fn AG_PixmapAddSurfaceFromFile
maps a surface obtained from an image file (format is autodetected).
.Pp
.Fn AG_PixmapSetSurface
changes the currently displayed surface (see
.Va n
in
.Sx STRUCTURE DATA ) .
The argument should be the handle of one of the surfaces previously
mapped with
.Fn AG_PixmapAddSurface .
.Pp
The
.Fn AG_PixmapGetSurface
returns a copy of the surface at given index (if the index is invalid then
a fatal condition is raised).
.Pp
The
.Fn AG_PixmapReplaceSurface
routine replaces the contents of the specified surface mapping.
.Pp
If the contents of a currently mapped surface are directly modified,
.Fn AG_PixmapUpdateSurface
should be called.
This routine may or may not be a no-op depending on the graphics mode.
.Pp
.Fn AG_PixmapSizeHint
requests a specific geometry in pixels.
The default geometry is that of the source surface passed to the constructor.
.Pp
The
.Fn AG_PixmapSetCoords
function changes the source coordinates of the active surface.
The default is [0,0].
.Sh EVENTS
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Pixmap
object:
.Bl -tag -width "int s, t "
.It Ft int n
Handle of currently displayed surface (-1 = none).
.It Ft int s, t
Source surface coordinates.
Can be set using
.Fn AG_PixmapSetCoords .
.El
.Sh EXAMPLES
The following code fragment displays an existing
.Xr AG_Surface 3 .
It packs
.Nm
in a
.Xr AG_Scrollview 3
widget, allowing the user to pan the view:
.Bd -literal -offset indent
.\" SYNTAX(c)
AG_Scrollview *sv;
AG_Pixmap *px;

sv = AG_ScrollviewNew(window, AG_SCROLLVIEW_BY_MOUSE |
                              AG_SCROLLVIEW_EXPAND);

px = AG_PixmapFromSurface(sv, 0, mySurface);
.Ed
.Pp
The following code fragment displays some image files:
.Bd -literal -offset indent
.\" SYNTAX(c)
AG_PixmapFromFile(sv, 0, "foo.png");
AG_PixmapFromFile(sv, 0, "bar.jpg");
.Ed
.Pp
The following code fragment loads 30 frames in JPEG format:
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
}
.Ed
.Pp
Running from a separate thread, the following code fragment would
play back the animation:
.Bd -literal -offset indent
.\" SYNTAX(c)
for (i = 0; i < 30; i++) {
	AG_PixmapSetSurface(px, frames[i]);
	AG_Delay(10);
}
.Ed
.Sh SEE ALSO
.Xr AG_Fixed 3 ,
.Xr AG_Intro 3 ,
.Xr AG_Scrollview 3 ,
.Xr AG_Surface 3 ,
.Xr AG_View 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Pp
See
.Pa tests/fixedres.c
in the Agar source distribution.
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
.Fn AG_PixmapGetSurface
appeared in Agar 1.6.0.