.\" Copyright (c) 2002-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 August 23, 2002
.Dt AG_VIEW 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_View
.Nd agar-gui display interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The Agar
.Nm
interface provides low-level video functions to the Agar GUI.
Every display is described by the
.Nm
structure, and is associated with a set of GUI windows (see the
.Dq WINDOW SYSTEM
section).
.Pp
The
.Nm
interface also implements a series of macros for basic pixel operations, and
a number of utility routines for surface and texture manipulation.
.Sh INTERFACE
.nr nS 1
.Ft "int"
.Fn AG_InitVideo "int w" "int h" "int bpp" "Uint flags"
.Pp
.Ft "void"
.Fn AG_DestroyVideo "void"
.Pp
.Ft "int"
.Fn AG_ResizeDisplay "int w" "int h"
.Pp
.Ft "int"
.Fn AG_SetRefreshRate "int fps"
.Pp
.Ft "void"
.Fn AG_SetVideoResizeCallback "void (*fn)(Uint w, Uint h)"
.Pp
.Ft void
.Fn AG_BindGlobalKey "SDLKey key" "SDLMod mod" "void (*fn)(void)"
.Pp
.Ft void
.Fn AG_BindGlobalKeyEv "SDLKey key" "SDLMod mod" "void (*fn)(AG_Event *)"
.Pp
.Ft int
.Fn AG_UnbindGlobalKey "SDLKey key" "SDLMod mod"
.Pp
.Ft void
.Fn AG_ClearGlobalKeys "void"
.Pp
.Ft "void"
.Fn AG_ViewUpdateFB "const AG_Rect2 *r"
.Pp
.Ft "void"
.Fn AG_LockView "void"
.Pp
.Ft "void"
.Fn AG_UnlockView "void"
.Pp
.nr nS 0
The
.Fn AG_InitVideo
function initializes the graphic display if there is one available,
returning 0 on success and -1 on failure.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_VIDEO_OPENGL_OR_SDL "
.It AG_VIDEO_HWSURFACE
Request hardware framebuffer, whenever possible.
.It AG_VIDEO_ASYNCBLIT
If SDL is selected as a back-end, pass the
.Dv SDL_ASYNCBLIT
flag to
.Xr SDL_SetVideoMode 3 .
.It AG_VIDEO_ANYFORMAT
In SDL mode, avoid emulating surface of requested depth if not available.
.It AG_VIDEO_HWPALETTE
In color-index mode, request exclusive palette access.
.It AG_VIDEO_DOUBLEBUF
If
.Dv AG_VIDEO_HWSURFACE
is used, enable hardware double-buffering.
.It AG_VIDEO_FULLSCREEN
Start in full screen mode.
.It AG_VIDEO_RESIZABLE
If display is windowed, request a resizable window.
.It AG_VIDEO_NOFRAME
If display is windowed, request a frame-less window.
.It AG_VIDEO_BGPOPUPMENU
When the user clicks on the background, display a generic popup menu,
by default listing the minimize windows.
.It AG_VIDEO_OPENGL
Request OpenGL mode and fail if it is not available.
.It AG_VIDEO_OPENGL_OR_SDL
Request OpenGL mode if it is available, and fallback to SDL.
.El
.Pp
The
.Fn AG_DestroyVideo
function frees all resources allocated to the GUI.
It is invoked automatically by
.Xr AG_Destroy 3 .
.Pp
The
.Fn AG_ResizeDisplay
function attempts to resize the display, assuming that the underlying
graphics system allows such an operation.
.Pp
The
.Fn AG_SetRefreshRate
function sets the maximum refresh rate, given in frames/second.
The stock event loop function
.Xr AG_EventLoop_FixedFPS 3
will attempt to draw exactly this number of frames per second and then idle
as much as possible.
This value is only advisory, alternate or user-defined event loop functions
may ignore it entirely.
.Pp
.Fn AG_SetVideoResizeCallback
configures a routine that will be invoked, whenever the display is resized
(assuming the display is resizable).
The
.Fa w ,
.Fa h
arguments are the new geometry in pixels.
.Pp
.Fn AG_BindGlobalKey
arranges for the given function to be invoked whenever the user presses the
given key combination, regardless of widgets.
The
.Fn AG_BindGlobalKeyEv
variant accepts an
.Xr AG_Event 3
style function.
.Fn AG_UnbindGlobalKey
removes the given key mapping, returning 0 on success and -1 if no such
mapping exists.
.Pp
.Fn AG_ClearGlobalKeys
removes all existing key mappings.
.Pp
The
.Fn AG_ViewUpdateFB
routine queues the update of a video region for the next event processing
cycle.
If the current display mode is not framebuffer-based,
.Fn AG_ViewUpdateFB
is a no-op.
.Pp
.Fn AG_LockView
and
.Fn AG_UnlockView
acquire and release the locks protecting direct framebuffer access.
If the display is not framebuffer-based or direct access does not require
locking, these functions are no-ops.
.Sh FRAMEBUFFER-SPECIFIC OPERATIONS
The following operations are only available when the current display surface
provides an accessible framebuffer.
.Pp
.nr nS 1
.Ft "void"
.Fn AG_VIEW_PUT_PIXEL "Uint8 *p" "Uint32 c"
.Pp
.Ft "void"
.Fn AG_VIEW_PUT_PIXEL2 "int x" "int y" "Uint32 c"
.Pp
.Ft "void"
.Fn AG_VIEW_PUT_PIXEL2_CLIPPED "int x" "int y" "Uint32 c"
.Pp
.Ft "void"
.Fn AG_ViewUpdateFB "const AG_Rect *r"
.Pp
.nr nS 0
The
.Fn AG_VIEW_PUT_PIXEL
and
.Fn AG_VIEW_PUT_PIXEL2
macros sets the value of a display pixel using a similar interface to
.Xr AG_PUT_PIXEL 3
and
.Xr AG_PUT_PIXEL2 3 .
The operation is optimized for the pixel format of the display surface.
It is unsafe to invoke these macros unless the current display surface is
framebuffer-based.
.Pp
.Fn AG_VIEW_PUT_PIXEL2_CLIPPED
tests the given coordinates against the current clipping rectangle (see
.Xr AG_WidgetPushClipRect 3 ,
.Xr AG_WidgetPopClipRect 3 ,
.Xr AG_SetClipRect 3 ) .
.Pp
The
.Fn AG_ViewUpdateFB
routine marks the specified video region for subsequent video updates.
.Sh OPENGL-SPECIFIC OPERATIONS
The following operations are only available when the current display surface
has an associated OpenGL context.
.Pp
.nr nS 1
.Ft "GLuint"
.Fn AG_SurfaceTexture "AG_Surface *src" "GLfloat *texcoord"
.Pp
.Ft "void"
.Fn AG_UpdateTexture "AG_Surface *src" "GLuint name"
.Pp
.Ft "AG_Surface *"
.Fn AG_CaptureGLView "void"
.Pp
.nr nS 0
.Fn AG_SurfaceTexture
creates an OpenGL texture from
.Fa src ,
returning the GL surface handel.
Texture coordinates (described as 4
.Ft float
values) is returned into
.Fa texcoord ,
is non-NULL.
.Pp
The
.Fn AG_UpdateTexture
routine updates the contents of an existing OpenGL texture from the contents
of a specified
.Ft AG_Surface .
.Fa name
specifies the GL texture handle.
.Pp
The
.Fn AG_CaptureGLView
function captures the contents of the current OpenGL display into an
.Ft AG_Surface .
The surface must be freed after use.
.Sh WINDOW SYSTEM
.nr nS 1
.Ft "void"
.Fn AG_ViewAttach "AG_Window *child"
.Pp
.Ft "void"
.Fn AG_ViewDetach "AG_Window *child"
.Pp
.Ft void
.Fn AG_ViewDetachQueued "void"
.Pp
.Ft "AG_Window *"
.Fn AG_FindWindow "char *name"
.Pp
.nr nS 0
The Agar GUI operates on a set of windows which are associated with an
.Nm .
For more details, see
.Xr AG_Window 3 .
.Pp
The
.Fn AG_ViewAttach
function attaches the window pointed to by
.Fa child
to the view.
The
.Fn AG_ViewDetach
function detaches the window pointed to by
.Fa child
from the view by adding it to the detach queue.
The detachment will be performed later by
.Fa AG_ViewDetachQueued .
.Pp
The
.Fn AG_FindWindow
functions looks for a window identified by
.Fa name
and return NULL if there is no such window.
.Sh STRUCTURE DATA
For the
.Ft AG_View
object:
.Pp
.Bl -tag -width "TAILQ windows "
.It Ft int w, h
Dimensions of the display in pixels (read-only).
.It Ft int depth
Color depth of the display in bits per pixel (read-only).
.It Ft int rCur
Current refresh rate (exact interpretation left to event loop).
.It Ft Uint rNom
Nominal refresh rate (exact interpretation left to event loop).
.It Ft AG_Mutex lock
Lock on GUI window lists.
.It Ft TAILQ windows
List of
.Xr AG_Window 3
objects associated with display (read-only).
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Rect 3 ,
.Xr AG_Surface 3 ,
.Xr AG_Window 3 ,
.Xr SDL_SetVideoMode 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.0