NAME

AG_GL — agar OpenGL specific routines

SYNOPSIS

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

DESCRIPTION

This manual page documents the OpenGL-specific functions exported by Agar. These functions are available if Agar was compiled with OpenGL support (i.e., HAVE_OPENGL is defined after including the headers above).

Those functions are mostly useful for implementing new OpenGL-based Agar drivers (see AG_Driver(3)). Some of these functions are also useful to simplify texture management when implementing OpenGL-specific Agar-GUI widgets.

OPENGL CONTEXT MANAGEMENT

void
AG_GL_InitContext(void *drv, AG_GL_Context *gl);

void
AG_GL_SetViewport(void *drv, const AG_Rect *rect);

void
AG_GL_DestroyContext(void *drv);

The AG_GL_InitContext() function is to be invoked by OpenGL-specific Agar drivers to initialize the GL context for rendering Agar GUI elements. This involves setting the projection and view matrices as well as various OpenGL options. AG_GL_InitContext() saves the current OpenGL state so that it can be later restored. The gl argument should point to an uninitialized AG_GL_Context structure.

The AG_GL_SetViewPort() function configures the GL viewport. In addition to invoking glViewport(3), this function also updates internal resolution-dependent states.

The AG_GL_DestroyContext() routines frees Agar's internal OpenGL state (restoring the state previously saved in AG_GL_InitContext()).

Multiple-window drivers will typically create a single OpenGL context per window, but single-window drivers may initialize and destroy the GL state more than once (see the AG_DRIVER_SW_OVERLAY option in AG_DriverSw(3)).

TEXTURE/SURFACE MANAGEMENT

void
AG_GL_UploadTexture(AG_Driver *drv, Uint *texName, AG_Surface *suSrc, AG_TexCoord *tc);

void
AG_GL_UpdateTexture(AG_Driver *drv, Uint texName, AG_Surface *suSrc, AG_TexCoord *tc);

void
AG_GL_DeleteTexture(AG_Driver *drv, Uint texName);

void
AG_GL_DeleteList(AG_Driver *drv, Uint listName);

void
AG_GL_BlitSurface(AG_Driver *drv, AG_Widget *wid, AG_Surface *s, int x, int y);

void
AG_GL_BlitSurfaceFrom(AG_Driver *drv, AG_Widget *widSrc, int surfName, AG_Rect *r, int x, int y);

void
AG_GL_BlitSurfaceGL(AG_Driver *drv, AG_Widget *wid, AG_Surface *s, float w, float h);

void
AG_GL_BlitSurfaceFromGL(AG_Driver *drv, AG_Widget *wid, int surfName, float w, float h);

void
AG_GL_BlitSurfaceFlippedGL(AG_Driver *drv, AG_Widget *wid, int surfName, float w, float h);

void
AG_GL_BackupSurfaces(AG_Driver *drv, AG_Widget *wid);

void
AG_GL_RestoreSurfaces(AG_Driver *drv, AG_Widget *wid);

void
AG_GL_RenderToSurface(AG_Driver *drv, AG_Widget *wid, AG_Surface **sDst);

The AG_GL_UploadTexture() operation converts the specified AG_Surface(3) to an OpenGL texture, returning the GL texture handle in texName. Texture coordinates are returned into tc if non-NULL (i.e., X/Y coordinates are 0.0 and width/height are computed from the original dimensions divided by the texture's power-of-two dimensions).

The AG_GL_UpdateTexture() operation uploads a new surface as the specified texture ID. Similarly to AG_GL_UploadTexture(), texture coordinates are returned into tc if non-NULL.

The AG_GL_DeleteTexture() operation arranges for the specified GL texture to be deleted as soon as possible. Unlike a direct call to glDeleteTextures(3), using the AG_GL_DeleteTexture() function is thread-safe.

Similarly, AG_GL_DeleteList() arranges for the given GL display list to be deleted as soon as possible.

The remaining functions AG_GL_BlitSurface(), AG_GL_BlitSurfaceFrom(), etc. are generic OpenGL backends to the corresponding driver surface/texture operations (i.e., blitSurface(), blitSurfaceFrom(), etc.) See AG_Driver(3) for details.

RENDERING PRIMITIVES

void
AG_GL_FillRect(AG_Driver *drv, AG_Rect r, AG_Color c);

void
AG_GL_PutPixel(AG_Driver *drv, int x, int y, AG_Color c);

void
AG_GL_PutPixel32(AG_Driver *drv, int x, int y, Uint32 c);

void
AG_GL_PutPixelRGB(AG_Driver *drv, int x, int y, Uint8 r, Uint8 g, Uint8 b);

void
AG_GL_BlendPixel(AG_Driver *drv, int x, int y, AG_Color C, AG_AlphaFn fnSrc, AG_AlphaFn fnDst);

void
AG_GL_DrawLine(AG_Driver *drv, int x1, int y1, int x2, int y2, AG_Color C);

void
AG_GL_DrawLineH(AG_Driver *drv, int x1, int x2, int y, AG_Color c);

void
AG_GL_DrawLineV(AG_Driver *drv, int x, int y1, int y2, AG_Color c);

void
AG_GL_DrawLineBlended(AG_Driver *drv, int x1, int y1, int x2, int y2, AG_Color c, AG_AlphaFn fnSrc, AG_AlphaFn fnDst);

void
AG_GL_DrawArrowUp(AG_Driver *drv, int x, int y, int h, AG_Color C[2]);

void
AG_GL_DrawArrowDown(AG_Driver *drv, int x, int y, int h, AG_Color C[2]);

void
AG_GL_DrawArrowLeft(AG_Driver *drv, int x, int y, int h, AG_Color C[2]);

void
AG_GL_DrawArrowRight(AG_Driver *drv, int x, int y, int h, AG_Color C[2]);

void
AG_GL_DrawRectDithered(AG_Driver *drv, AG_Rect r, AG_Color c);

void
AG_GL_DrawBoxRounded(AG_Driver *drv, AG_Rect r, int z, int radius, AG_Color C[3]);

void
AG_GL_DrawBoxRoundedTop(AG_Driver *drv, AG_Rect r, int z, int radius, AG_Color C[3]);

void
AG_GL_DrawCircle(AG_Driver *drv, int x, int y, int r, AG_Color C);

void
AG_GL_DrawCircle2(AG_Driver *drv, int x, int y, int r, AG_Color C);

void
AG_GL_DrawRectFilled(AG_Driver *drv, AG_Rect r, AG_Color c);

void
AG_GL_DrawRectBlended(AG_Driver *drv, AG_Rect r, AG_Color c, AG_AlphaFn fnSrc, AG_AlphaFn fnDst);

void
AG_GL_UpdateGlyph(AG_Driver *drv, AG_Glyph *glyph);

void
AG_GL_DrawGlyph(AG_Driver *drv, const AG_Glyph *glyph, int x, int y);

These functions are generic OpenGL backends to the corresponding driver surface/texture operations (e.g., fillRect(), putPixel(), etc); see AG_Driver(3) for details.

HISTORY

The AG_GL interface first appeared in Agar 1.4.0.