.\" Copyright (c) 2010-2022 Julien Nadeau Carriere .\" 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_GL 3 .Os Agar 1.7 .Sh NAME .Nm AG_GL .Nd agar OpenGL specific routines .Sh SYNOPSIS .Bd -literal #include #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_GLView.png, "The AG_GLView(3) widget") This manual page documents the OpenGL-specific functions exported by Agar. These functions are available if Agar was compiled with OpenGL support (i.e., .Dv HAVE_OPENGL is defined after including the headers above). .Pp Those functions are mostly useful for implementing new OpenGL-based Agar drivers (see .Xr AG_Driver 3 ) . Some of these functions are also useful to simplify texture management when implementing OpenGL-specific Agar-GUI widgets. .Sh OPENGL CONTEXT MANAGEMENT .nr nS 1 .Ft "void" .Fn AG_GL_InitContext "void *drv" "AG_GL_Context *gl" .Pp .Ft "void" .Fn AG_GL_SetViewport "void *drv" "const AG_Rect *rect" .Pp .Ft "void" .Fn AG_GL_DestroyContext "void *drv" .Pp .nr nS 0 The .Fn 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. .Fn AG_GL_InitContext saves the current OpenGL state so that it can be later restored. The .Fa gl argument should point to an uninitialized .Ft AG_GL_Context structure. .Pp The .Fn AG_GL_SetViewPort function configures the GL viewport. In addition to invoking .Xr glViewport 3 , this function also updates internal resolution-dependent states. .Pp The .Fn AG_GL_DestroyContext routines frees Agar's internal OpenGL state (restoring the state previously saved in .Fn AG_GL_InitContext ) . .Pp 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 .Dv AG_DRIVER_SW_OVERLAY option in .Xr AG_DriverSw 3 ) . .Sh TEXTURE/SURFACE MANAGEMENT .nr nS 1 .Ft "void" .Fn AG_GL_UploadTexture "AG_Driver *drv" "Uint *texName" "AG_Surface *suSrc" "AG_TexCoord *tc" .Pp .Ft "void" .Fn AG_GL_UpdateTexture "AG_Driver *drv" "Uint texName" "AG_Surface *suSrc" "AG_TexCoord *tc" .Pp .Ft "void" .Fn AG_GL_DeleteTexture "AG_Driver *drv" "Uint texName" .Pp .Ft "void" .Fn AG_GL_DeleteList "AG_Driver *drv" "Uint listName" .Pp .Ft "void" .Fn AG_GL_BlitSurface "AG_Driver *drv" "AG_Widget *wid" "AG_Surface *s" "int x" "int y" .Pp .Ft "void" .Fn AG_GL_BlitSurfaceFrom "AG_Driver *drv" "AG_Widget *widSrc" "int surfName" "AG_Rect *r" "int x" "int y" .Pp .Ft "void" .Fn AG_GL_BlitSurfaceGL "AG_Driver *drv" "AG_Widget *wid" "AG_Surface *s" "float w" "float h" .Pp .Ft "void" .Fn AG_GL_BlitSurfaceFromGL "AG_Driver *drv" "AG_Widget *wid" "int surfName" "float w" "float h" .Pp .Ft "void" .Fn AG_GL_BlitSurfaceFlippedGL "AG_Driver *drv" "AG_Widget *wid" "int surfName" "float w" "float h" .Pp .Ft "void" .Fn AG_GL_BackupSurfaces "AG_Driver *drv" "AG_Widget *wid" .Pp .Ft "void" .Fn AG_GL_RestoreSurfaces "AG_Driver *drv" "AG_Widget *wid" .Pp .Ft "void" .Fn AG_GL_RenderToSurface "AG_Driver *drv" "AG_Widget *wid" "AG_Surface **sDst" .Pp .nr nS 0 The .Fn AG_GL_UploadTexture operation converts the specified .Xr AG_Surface 3 to an OpenGL texture, returning the GL texture handle in .Fa texName . Texture coordinates are returned into .Fa 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). .Pp The .Fn AG_GL_UpdateTexture operation uploads a new surface as the specified texture ID. Similarly to .Fn AG_GL_UploadTexture , texture coordinates are returned into .Fa tc if non-NULL. .Pp The .Fn AG_GL_DeleteTexture operation arranges for the specified GL texture to be deleted as soon as possible. Unlike a direct call to .Xr glDeleteTextures 3 , using the .Fn AG_GL_DeleteTexture function is thread-safe. .Pp Similarly, .Fn AG_GL_DeleteList arranges for the given GL display list to be deleted as soon as possible. .Pp The remaining functions .Fn AG_GL_BlitSurface , .Fn AG_GL_BlitSurfaceFrom , etc. are generic OpenGL backends to the corresponding driver surface/texture operations (i.e., .Fn blitSurface , .Fn blitSurfaceFrom , etc.) See .Xr AG_Driver 3 for details. .Sh RENDERING PRIMITIVES .nr nS 1 .Ft void .Fn AG_GL_FillRect "AG_Driver *drv" "AG_Rect r" "AG_Color c" .Pp .Ft void .Fn AG_GL_PutPixel "AG_Driver *drv" "int x" "int y" "AG_Color c" .Pp .Ft void .Fn AG_GL_PutPixel32 "AG_Driver *drv" "int x" "int y" "Uint32 c" .Pp .Ft void .Fn AG_GL_PutPixelRGB "AG_Driver *drv" "int x" "int y" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft void .Fn AG_GL_BlendPixel "AG_Driver *drv" "int x" "int y" "AG_Color C" "AG_AlphaFn fnSrc" "AG_AlphaFn fnDst" .Pp .Ft void .Fn AG_GL_DrawLine "AG_Driver *drv" "int x1" "int y1" "int x2" "int y2" "AG_Color C" .Pp .Ft void .Fn AG_GL_DrawLineH "AG_Driver *drv" "int x1" "int x2" "int y" "AG_Color c" .Pp .Ft void .Fn AG_GL_DrawLineV "AG_Driver *drv" "int x" "int y1" "int y2" "AG_Color c" .Pp .Ft void .Fn AG_GL_DrawLineBlended "AG_Driver *drv" "int x1" "int y1" "int x2" "int y2" "AG_Color c" "AG_AlphaFn fnSrc" "AG_AlphaFn fnDst" .Pp .Ft void .Fn AG_GL_DrawArrowUp "AG_Driver *drv" "int x" "int y" "int h" "AG_Color C[2]" .Pp .Ft void .Fn AG_GL_DrawArrowDown "AG_Driver *drv" "int x" "int y" "int h" "AG_Color C[2]" .Pp .Ft void .Fn AG_GL_DrawArrowLeft "AG_Driver *drv" "int x" "int y" "int h" "AG_Color C[2]" .Pp .Ft void .Fn AG_GL_DrawArrowRight "AG_Driver *drv" "int x" "int y" "int h" "AG_Color C[2]" .Pp .Ft void .Fn AG_GL_DrawRectDithered "AG_Driver *drv" "AG_Rect r" "AG_Color c" .Pp .Ft void .Fn AG_GL_DrawBoxRounded "AG_Driver *drv" "AG_Rect r" "int z" "int radius" "AG_Color C[3]" .Pp .Ft void .Fn AG_GL_DrawBoxRoundedTop "AG_Driver *drv" "AG_Rect r" "int z" "int radius" "AG_Color C[3]" .Pp .Ft void .Fn AG_GL_DrawCircle "AG_Driver *drv" "int x" "int y" "int r" "AG_Color C" .Pp .Ft void .Fn AG_GL_DrawCircle2 "AG_Driver *drv" "int x" "int y" "int r" "AG_Color C" .Pp .Ft void .Fn AG_GL_DrawRectFilled "AG_Driver *drv" "AG_Rect r" "AG_Color c" .Pp .Ft void .Fn AG_GL_DrawRectBlended "AG_Driver *drv" "AG_Rect r" "AG_Color c" "AG_AlphaFn fnSrc" "AG_AlphaFn fnDst" .Pp .Ft void .Fn AG_GL_UpdateGlyph "AG_Driver *drv" "AG_Glyph *glyph" .Pp .Ft void .Fn AG_GL_DrawGlyph "AG_Driver *drv" "const AG_Glyph *glyph" "int x" "int y" .Pp .nr nS 0 These functions are generic OpenGL backends to the corresponding driver surface/texture operations (e.g., .Fn fillRect , .Fn putPixel , etc); see .Xr AG_Driver 3 for details. .Sh SEE ALSO .Xr AG_Driver 3 , .Xr AG_Intro 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 .Sh HISTORY The .Nm interface first appeared in Agar 1.4.0.