glutils.h File Reference

#include <stdio.h>
#include "assert.h"
#include "geom.h"
#include "glew.h"
#include "glutils_zink.h"
#include "log.h"
#include "safe_alloc.h"
#include "sysmacros.h"
#include <cglm/cglm.h>

Include dependency graph for glutils.h:

Go to the source code of this file.

Data Structures
struct	glutils_quads_t
struct	glutils_lines_t

Macros
#define	MAT4_ALLOC_ALIGN   16
#define	glutils_init_2D_quads(__quads, __p, __t, __num_pts)
#define	glutils_update_2D_quads(__quads, __p, __t, __num_pts)
#define	glutils_init_3D_quads(__quads, __p, __t, __num_pts)
#define	glutils_update_3D_quads(__quads, __p, __t, __num_pts)
#define	glutils_init_3D_lines(__lines, __p, __num_pts)
#define	GLUTILS_VALIDATE_INDICES(indices, num_idx, num_vtx)
#define	TEXSZ_MK_TOKEN(name)    static const char *__texsz_token_ ## name = #name
#define	TEXSZ_DECL_TOKEN_GLOB(name)    extern const char *__texsz_token_ ## name
#define	TEXSZ_DEF_TOKEN_GLOB(name)    const char *__texsz_token_ ## name = #name
#define	TEXSZ_ALLOC(__token_id, __format, __type, __w, __h)
#define	TEXSZ_FREE(__token_id, __format, __type, __w, __h)
#define	TEXSZ_ALLOC_INSTANCE(__token_id, __instance, __filename, __line, __format, __type, __w, __h)
#define	TEXSZ_FREE_INSTANCE(__token_id, __instance, __format, __type, __w, __h)
#define	TEXSZ_ALLOC_BYTES(__token_id, __bytes)    TEXSZ_ALLOC_BYTES_INSTANCE(__token_id, NULL, NULL, -1, (__bytes))
#define	TEXSZ_FREE_BYTES(__token_id, __bytes)    TEXSZ_FREE_BYTES_INSTANCE(__token_id, NULL, (__bytes))
#define	TEXSZ_ALLOC_BYTES_INSTANCE(__token_id, __instance, __filename, __line, __bytes)
#define	TEXSZ_FREE_BYTES_INSTANCE(__token_id, __instance, __bytes)
#define	IF_TEXSZ(__xxx)
#define	_LACF_RENDER_DEBUG   0
#define	GLUTILS_ASSERT_NO_ERROR()
#define	GLUTILS_ASSERT(_x_)
#define	GLUTILS_ASSERT_MSG(_x_, ...)
#define	GLUTILS_ASSERT3S(_x_, _y_, _z_)
#define	GLUTILS_ASSERT3U(_x_, _y_, _z_)
#define	GLUTILS_ASSERT3P(_x_, _y_, _z_)
#define	GLUTILS_RESET_ERRORS()

Typedefs
typedef void(*	glutils_texsz_enum_cb_t) (const char *token, int64_t bytes, void *userinfo)

Functions
void	glutils_sys_init (void)
void	glutils_disable_all_client_state (void)
void	glutils_disable_all_vtx_attrs (void)
GLuint	glutils_make_quads_IBO (size_t num_vtx)
static bool_t	glutils_quads_inited (const glutils_quads_t *quads)
void	glutils_init_2D_quads_impl (glutils_quads_t *quads, const char *filename, int line, const vect2_t *p, const vect2_t *t, size_t num_pts)
void	glutils_update_2D_quads_impl (glutils_quads_t *quads, const char *filename, int line, const vect2_t *p, const vect2_t *t, size_t num_pts)
void	glutils_init_3D_quads_impl (glutils_quads_t *quads, const char *filename, int line, const vect3_t *p, const vect2_t *t, size_t num_pts)
void	glutils_update_3D_quads_impl (glutils_quads_t *quads, const char *filename, int line, const vect3_t *p, const vect2_t *t, size_t num_pts)
void	glutils_destroy_quads (glutils_quads_t *quads)
void	glutils_draw_quads (glutils_quads_t *quads, GLint prog)
void	glutils_init_3D_lines_impl (glutils_lines_t *lines, const char *filename, int line, const vect3_t *p, size_t num_pts)
void	glutils_destroy_lines (glutils_lines_t *lines)
void	glutils_draw_lines (glutils_lines_t *lines, GLint prog)
glutils_cache_t *	glutils_cache_new (size_t cap_bytes)
void	glutils_cache_destroy (glutils_cache_t *cache)
glutils_quads_t *	glutils_cache_get_2D_quads (glutils_cache_t *cache, const vect2_t *p, const vect2_t *t, size_t num_pts)
glutils_quads_t *	glutils_cache_get_3D_quads (glutils_cache_t *cache, const vect3_t *p, const vect2_t *t, size_t num_pts)
glutils_lines_t *	glutils_cache_get_3D_lines (glutils_cache_t *cache, const vect3_t *p, size_t num_pts)
void	glutils_vp2pvm (GLfloat pvm[16])
void	glutils_texsz_init (void)
void	glutils_texsz_fini (void)
void	glutils_texsz_alloc (const char *token, const void *instance, const char *filename, int line, GLenum format, GLenum type, unsigned w, unsigned h)
void	glutils_texsz_free (const char *token, const void *instance, GLenum format, GLenum type, unsigned w, unsigned h)
void	glutils_texsz_alloc_bytes (const char *token, const void *instance, const char *filename, int line, int64_t bytes)
void	glutils_texsz_free_bytes (const char *token, const void *instance, int64_t bytes)
uint64_t	glutils_texsz_get (void)
void	glutils_texsz_enum (glutils_texsz_enum_cb_t cb, void *userinfo)
bool_t	glutils_texsz_inited (void)
bool_t	glutils_nsight_debugger_present (void)
static void	glutils_reset_errors (void)
static void	glutils_debug_push (GLuint msgid, const char *format,...)
static void	glutils_debug_pop (void)
glutils_nl_t *	glutils_nl_alloc_2D (const vec2 *pts, size_t num_pts)
glutils_nl_t *	glutils_nl_alloc_3D (const vec3 *pts, size_t num_pts)
void	glutils_nl_free (glutils_nl_t *nl)
void	glutils_nl_draw (glutils_nl_t *nl, float width, GLuint prog)
static void	glutils_enable_vtx_attr_ptr (GLint index, GLint size, GLenum type, GLboolean normalized, size_t stride, size_t offset)
static void	glutils_disable_vtx_attr_ptr (GLint index)
bool_t	glutils_png2gltexfmt (int png_color_type, int png_bit_depth, GLint *int_fmt, GLint *fmt, GLint *type)

Detailed Description

This module is an aggregation of various OpenGL utility functions and features. Check out the individual functions for what is available. Before you start using the functionality in this module, be sure to call glutils_sys_init(). There is no corresponding deinit function, so once initialized, there's nothing else to do.

Definition in file glutils.h.

Macro Definition Documentation

_LACF_RENDER_DEBUG

#define _LACF_RENDER_DEBUG   0

This macro controls whether the GLUTILS_ASSERT* and GLUTILS_RESET_ERRORS() macros are enabled. The default state is that these macros are disabled and do not get compiled into your code. If you want to enable them, define this macro to a non-zero value in your build system.

Definition at line 450 of file glutils.h.

GLUTILS_ASSERT

#define GLUTILS_ASSERT

(

_x_

)

Equivalent of a VERIFY() check, but only enabled if _LACF_RENDER_DEBUG is non-zero.

See also

_LACF_RENDER_DEBUG

Definition at line 503 of file glutils.h.

GLUTILS_ASSERT3P

#define GLUTILS_ASSERT3P	(		_x_,
			_y_,
			_z_
	)

Equivalent of a VERIFY3P() check, but only enabled if _LACF_RENDER_DEBUG is non-zero.

See also

_LACF_RENDER_DEBUG

Definition at line 507 of file glutils.h.

GLUTILS_ASSERT3S

#define GLUTILS_ASSERT3S	(		_x_,
			_y_,
			_z_
	)

Equivalent of a VERIFY3S() check, but only enabled if _LACF_RENDER_DEBUG is non-zero.

See also

_LACF_RENDER_DEBUG

Definition at line 505 of file glutils.h.

GLUTILS_ASSERT3U

#define GLUTILS_ASSERT3U	(		_x_,
			_y_,
			_z_
	)

Equivalent of a VERIFY3U() check, but only enabled if _LACF_RENDER_DEBUG is non-zero.

See also

_LACF_RENDER_DEBUG

Definition at line 506 of file glutils.h.

GLUTILS_ASSERT_MSG

#define GLUTILS_ASSERT_MSG	(		_x_,
			...
	)

Equivalent of a VERIFY_MSG() check, but only enabled if _LACF_RENDER_DEBUG is non-zero.

See also

_LACF_RENDER_DEBUG

Definition at line 504 of file glutils.h.

GLUTILS_ASSERT_NO_ERROR

#define GLUTILS_ASSERT_NO_ERROR

(

)

If enabled, this macro compiles to a hard assertion check, which verifies that the glGetError() functio returns no error. This can be used for debugging of drawing code, to make sure it generated no error. Enablement is controlled using the _LACF_RENDER_DEBUG macro.

See also

_LACF_RENDER_DEBUG

Definition at line 502 of file glutils.h.

glutils_init_2D_quads

#define glutils_init_2D_quads	(		__quads,
			__p,
			__t,
			__num_pts
	)

Value:

    glutils_init_2D_quads_impl((__quads), log_basename(__FILE__), \
        __LINE__, (__p), (__t), (__num_pts))

Same as glutils_init_3D_quads(), but expects an array of vect2_t points in the __p argument. The input data to the shader program will still be vec3's, but the Z coordinate will be zero.

Definition at line 144 of file glutils.h.

glutils_init_3D_lines

#define glutils_init_3D_lines	(		__lines,
			__p,
			__num_pts
	)

Value:

    glutils_init_3D_lines_impl((__lines), log_basename(__FILE__), \
        __LINE__, (__p), (__num_pts))

Deprecated:

The glutils_lines_t functionality is deprecated, as it relies on legacy GL_LINE_STRIP functionality of the OpenGL driver. See glutils_nl_t for a modern replacement.

Similar to glutils_init_3D_quads(), but utilizing a glutils_lines_t object. The initialized glutils_lines_t object can be passed to glutils_draw_lines() for rendering. When you are done with the object, you should dispose of it using glutils_destroy_lines().

Parameters

__lines	A pointer to a glutils_lines_t object to be initialized.
__p	A pointer to an array of vect3_t coordinates, which will be used as the points along the line strip.
__num_pts	Number of points in __p.

See also

glutils_lines_t

glutils_draw_lines()

glutils_destroy_lines()

Definition at line 209 of file glutils.h.

glutils_init_3D_quads

#define glutils_init_3D_quads	(		__quads,
			__p,
			__t,
			__num_pts
	)

Value:

    glutils_init_3D_quads_impl((__quads), log_basename(__FILE__), \
        __LINE__, (__p), (__t), (__num_pts))

Initializes a glutils_quads_t object.

Parameters

__quads	A pointer to the glutils_quads_t object to be initialized.
__p	A mandatory pointer to an array of vect3_t points, which will form the corners of the individual quads. This data will be passed to the shader program as vec3's.
__t	A optional pointer to an array of vect2_t UV coordinates, which will be passed to the shader as an additional input of vec2's. If you don't need this, simply pass NULL here.
__num_pts	Number of points in __p and __t.

See also

glutils_quads_t

Definition at line 170 of file glutils.h.

GLUTILS_RESET_ERRORS

#define GLUTILS_RESET_ERRORS

(

)

If enabled, calls glutils_reset_errors() to drain the OpenGL error stack for debugging purposes. Enablement is controlled by _LACF_RENDER_DEBUG.

See also

_LACF_RENDER_DEBUG

Definition at line 508 of file glutils.h.

glutils_update_2D_quads

#define glutils_update_2D_quads	(		__quads,
			__p,
			__t,
			__num_pts
	)

Value:

    glutils_update_2D_quads_impl((__quads), log_basename(__FILE__), \
        __LINE__, (__p), (__t), (__num_pts))

Same as glutils_update_3D_quads(), but expects 2D points.

Definition at line 152 of file glutils.h.

glutils_update_3D_quads

#define glutils_update_3D_quads	(		__quads,
			__p,
			__t,
			__num_pts
	)

Value:

    glutils_update_3D_quads_impl((__quads), log_basename(__FILE__), \
        __LINE__, (__p), (__t), (__num_pts))

Updates the vertex data in a glutils_quad_t object, which was previously initialized using glutils_init_3D_quads(). This replaces all vertex data in the quads with the new data provided in the arguments here. The meaning of the arguments is exactly the same as in glutils_init_3D_quads().

Definition at line 183 of file glutils.h.

GLUTILS_VALIDATE_INDICES

#define GLUTILS_VALIDATE_INDICES	(		indices,
			num_idx,
			num_vtx
	)

Value:

    do { \
        for (unsigned i = 0; i < (num_idx); i++) { \
            VERIFY_MSG((indices)[i] < (num_vtx), "invalid index " \
                "specification encountered, index %d (value %d) " \
                "is outside of vertex range %d", i, (indices)[i], \
                (num_vtx)); \
        } \
    } while (0)

Definition at line 232 of file glutils.h.

IF_TEXSZ

#define IF_TEXSZ

(

__xxx

)

Value:

    do { \
        if (glutils_texsz_inited()) { \
            __xxx; \
        } \
    } while (0)

Wrapper macro to execute an optional bit of code only if the TEXSZ debug system is in use. Wrap any usage of the TEXSZ_ALLOC* and TEXSZ_FREE* macros in this macro, to only enable them when the TEXSZ system has been initialized. You can also use this to control execution of your own reporting code.

Definition at line 434 of file glutils.h.

MAT4_ALLOC_ALIGN

#define MAT4_ALLOC_ALIGN   16

Definition at line 56 of file glutils.h.

TEXSZ_ALLOC

#define TEXSZ_ALLOC	(		__token_id,
			__format,
			__type,
			__w,
			__h
	)

Value:

    TEXSZ_ALLOC_INSTANCE(__token_id, NULL, NULL, -1, (__format), \
        (__type), (__w), (__h))

Notifies the TEXSZ system of a texture allocation by incrementing the token's byte counter. Every call to TEXSZ_ALLOC() must be balanced by call to TEXSZ_FREE(). If a token is non-zero at the time glutils_texsz_fini() is called, the offending token name(s) are printed in sequence, with the amount of bytes leaked in them. In this mode, no filenames or line numbers are printed.

Parameters

__token_id	The token name previously created using TEXSZ_MK_TOKEN().
__format	The texture format (e.g. GL_RGBA).
__type	The texture data type (e.g. GL_UNSIGNED_BYTE).
__w	Texture width in pixels.
__h	Texture height in pixels.

Definition at line 326 of file glutils.h.

TEXSZ_ALLOC_BYTES

#define TEXSZ_ALLOC_BYTES	(		__token_id,
			__bytes
	)		TEXSZ_ALLOC_BYTES_INSTANCE(__token_id, NULL, NULL, -1, (__bytes))

Same as TEXSZ_ALLOC(), but rather than taking texture information to calculate the allocation size, takes an explicit byte count as an argument. This lets you use the TEXSZ machinery to track allocations which are not textures (e.g. vertex buffers).

Definition at line 383 of file glutils.h.

TEXSZ_ALLOC_BYTES_INSTANCE

#define TEXSZ_ALLOC_BYTES_INSTANCE	(		__token_id,
			__instance,
			__filename,
			__line,
			__bytes
	)

Value:

    glutils_texsz_alloc_bytes(__texsz_token_ ## __token_id, (__instance), \
        (__filename), (__line), (__bytes))

Instanced variant of TEXSZ_ALLOC_BYTES(). The __instance argument matches the behavior of TEXSZ_ALLOC_INSTANCE() instance argument.

See also

TEXSZ_ALLOC_BYTES()

TEXSZ_ALLOC_INSTANCE()

Definition at line 398 of file glutils.h.

TEXSZ_ALLOC_INSTANCE

#define TEXSZ_ALLOC_INSTANCE	(		__token_id,
			__instance,
			__filename,
			__line,
			__format,
			__type,
			__w,
			__h
	)

Value:

    glutils_texsz_alloc(__texsz_token_ ## __token_id, (__instance), \
        (__filename), (__line), (__format), (__type), (__w), (__h))

Performs a similar function to TEXSZ_ALLOC(), but allows for more granular tracking than per-whole-token. To allow you to keep track of individual allocations, this macro takes two additional parameters over TEXSZ_ALLOC():

Parameters

__instance	An instance pointer - this is used to discriminate individual allocations. Usually you'd want to pass a containing structure pointer or something similar in here.
__filename	An allocation point filename.
__line	An allocation point line number.

The filename should be shortened at build time using log_backtrace() to only contain the last portion of the filename of the call site. You should wrap your functions which use TEXSZ_ALLOC_INSTANCE() into a macro and extract the call site information automatically using the __FILE__ and __LINE__ built-in pre-processor variables (see the glutils_init_*_quads() functions for an example on how to do that). With instancing, glutils_texsz_fini() will print a list of leaked instance pointers and call sites in your code where that resource was leaked.

Allocations registered using TEXSZ_ALLOC_INSTANCE() must be freed using the TEXSZ_FREE_INSTANCE() macro, with the original pointer used in the __instance argument.

Definition at line 361 of file glutils.h.

TEXSZ_DECL_TOKEN_GLOB

#define TEXSZ_DECL_TOKEN_GLOB

(

name

)

extern const char *__texsz_token_ ## name

Declares a global TEXSZ system tracking token. Place this into a header which will be included from all modules which will need to use this token.

See also

TEXSZ_MK_TOKEN

Definition at line 303 of file glutils.h.

TEXSZ_DEF_TOKEN_GLOB

#define TEXSZ_DEF_TOKEN_GLOB

(

name

)

const char *__texsz_token_ ## name = #name

Defines a global TEXSZ system tracking token. Place this into a single implementation modules, which is where the token will live.

See also

TEXSZ_MK_TOKEN

Definition at line 310 of file glutils.h.

TEXSZ_FREE

#define TEXSZ_FREE	(		__token_id,
			__format,
			__type,
			__w,
			__h
	)

Value:

    TEXSZ_FREE_INSTANCE(__token_id, NULL, (__format), \
        (__type), (__w), (__h))

Notifies the TEXSZ system of a texture deallocation. The resouce must have previously been registered using the TEXSZ_ALLOC() macro. All arguments in this macro have the same meaning as in TEXSZ_ALLOC().

Definition at line 334 of file glutils.h.

TEXSZ_FREE_BYTES

#define TEXSZ_FREE_BYTES	(		__token_id,
			__bytes
	)		TEXSZ_FREE_BYTES_INSTANCE(__token_id, NULL, (__bytes))

Same as TEXSZ_FREE(), but rather than taking texture information to calculate the allocation size, takes an explicit byte count as an argument. This basically undoes a TEXSZ_ALLOC_BYTES() operation.

Definition at line 390 of file glutils.h.

TEXSZ_FREE_BYTES_INSTANCE

#define TEXSZ_FREE_BYTES_INSTANCE	(		__token_id,
			__instance,
			__bytes
	)

Value:

    glutils_texsz_free_bytes(__texsz_token_ ## __token_id, (__instance), \
        (__bytes))

Instanced variant of TEXSZ_FREE_BYTES(). The __instance argument matches the behavior of TEXSZ_FREE_INSTANCE() instance argument.

See also

TEXSZ_FREE_BYTES()

TEXSZ_FREE_INSTANCE()

Definition at line 408 of file glutils.h.

TEXSZ_FREE_INSTANCE

#define TEXSZ_FREE_INSTANCE	(		__token_id,
			__instance,
			__format,
			__type,
			__w,
			__h
	)

Value:

    glutils_texsz_free(__texsz_token_ ## __token_id, (__instance), \
        (__format), (__type), (__w), (__h))

Frees an instanced allocation, previously registered using TEXSZ_ALLOC_INSTANCE(). You must use the same __instance pointer as was used for the allocation. There is no filename or line argument anymore, since they are only stored in the allocation information. The allocation MUST exist, otherwise this macro causes an assertion failure.

Definition at line 373 of file glutils.h.

TEXSZ_MK_TOKEN

#define TEXSZ_MK_TOKEN

(

name

)

static const char *__texsz_token_ ## name = #name

The TEXSZ infrastructure is for debugging GPU VRAM memory leaks.

At plugin load time (in XPluginStart and before doing any libacfutils calls that might generate OpenGL calls), you must first initialize the system using a call to glutils_texsz_init(). At plugin exit time, and after having torn down all resources, call glutils_texsz_fini(). This collects all garbage and crashes the app with diagnostic information in case any leaks have been detected.

Each allocation can be tracked in a two-level hierarchy:

• using a symbolic token name
  • each token can track allocations to a particular anonymous pointer (plus a filename:line tuple where it occurred)

The tokens are used to identify large blocks of functionality. You'd use a token for, for example, "efis_textures" or "custom_drawing_pbo", etc. These must be declared ahead at the top of each module file using the TEXSZ_MK_TOKEN macro, for example:

TEXSZ_MK_TOKEN(efis_textures);

Don't put spaces into the token name, the name must be a valid C identifier. You can subsequently track allocations to this token using the TEXSZ_ALLOC() and TEXSZ_FREE() macros.

Please note that TEXSZ_MK_TOKEN() creates a static (single-module) token that cannot be shared between multiple C files. If you plan on using a TEXSZ token from more than one C/C++ file, you must declare the token in a header file using the TEXSZ_DECL_TOKEN_GLOB() macro instead. Then define the token in a single C file using TEXSZ_DEF_TOKEN_GLOB:

TEXSZ_DECL_TOKEN_GLOB(efis_textures);   <--- goes in a header file

TEXSZ_DEF_TOKEN_GLOB(efis_textures);    <--- goes in a *single* C file

In case you are using a generic facility (e.g. a picture loader) to provide texturing service to other parts of the code, a simple token name might not be specific enough to pinpoint the offending allocation. In that case, you can use the TEXSZ_ALLOC_INSTANCE() and TEXSZ_FREE_INSTANCE() macros to generate per-pointer statistics.

In addition to the TEXSZ_ALLOC_* and TEXSZ_FREE_* macros, there are variations of these macros with the "_BYTES" suffix. These let you pass the raw byte size of the allocation directly, instead of having to pass texture formats and sizes. Use these when the data isn't a texture, but instead something more generic, like a vertex buffer.

See also

TEXSZ_ALLOC_BYTES()

TEXSZ_FREE_BYTES()

TEXSZ_ALLOC_BYTES_INSTANCE()

TEXSZ_FREE_BYTES_INSTANCE()

Definition at line 296 of file glutils.h.

Typedef Documentation

glutils_texsz_enum_cb_t

typedef void(* glutils_texsz_enum_cb_t) (const char *token, int64_t bytes, void *userinfo)

This callback is what you need to pass to glutils_texsz_enum().

Parameters

token	This is the name of texture allocation token in which this allocation was performed.
bytes	Number of bytes allocated in the respective token
userinfo	User info pointer passed to glutils_texsz_enum() in the userinfo argument.

Definition at line 115 of file glutils.h.

Function Documentation

glutils_cache_destroy()

void glutils_cache_destroy

(

glutils_cache_t *

cache

)

Destroys a glutils object cache. This frees all stored objects and their associated memory from both main memory and GPU memory.

Definition at line 484 of file glutils.c.

glutils_cache_get_2D_quads()

glutils_quads_t * glutils_cache_get_2D_quads	(	glutils_cache_t *	cache,
		const vect2_t *	p,
		const vect2_t *	t,
		size_t	num_pts
	)

Same as glutils_cache_get_3D_quads(), but for 2D quads.

See also

glutils_cache_get_3D_quads()

Definition at line 613 of file glutils.c.

glutils_cache_get_3D_lines()

glutils_lines_t * glutils_cache_get_3D_lines	(	glutils_cache_t *	cache,
		const vect3_t *	p,
		size_t	num_pts
	)

Deprecated:

The glutils_lines_t functionality is deprecated, as it relies on legacy GL_LINE_STRIP functionality of the OpenGL driver. See glutils_nl_t for a modern replacement.

Same as glutils_cache_get_3D_quads(), but for glutils_lines_t objects.

Definition at line 652 of file glutils.c.

glutils_cache_get_3D_quads()

glutils_quads_t * glutils_cache_get_3D_quads	(	glutils_cache_t *	cache,
		const vect3_t *	p,
		const vect2_t *	t,
		size_t	num_pts
	)

Mirrors the behavior of the glutils_init_3D_quads() macro, but utilizing the object cache in the cache argument. The cache looks for a glutils_quads_t matching the p and (optionally, if non-NULL) t argument contents. If an object was found, it is returned and can be used for drawing. The cache automatically trims out old cached objects, in order to stay within its allocation limits.

Returns

A glutils_quads_t object matching the passed p and t point arrays. The returned object is suitable for use in glutils_draw_quads(). The object may be deallocated due to subsequent object requests causing old objects to be freed, so you MUSTN'T keep this pointer beyond your immediate drawing needs. The object should be re-requested from the cache every time you need to draw it. You must also NOT glutils_quads_free() this object, or you will cause use of invalid memory. The cache handles object lifetimes completely.

Definition at line 638 of file glutils.c.

glutils_cache_new()

glutils_cache_t * glutils_cache_new

(

size_t

cap_bytes

)

Constructs a new object cache with a certain defined capacity in bytes. This cache lets you construct & cache glutils_quads_t and glutils_lines_t objects on the GPU. Use glutils_cache_get_* to store & retrieve cached objects. When the cache is destroyed, the stored objects are destroyed and their memory freed from the GPU.

The cache is an LRU cache, so it remembers which objects were used most recently and releases the least-recently-used when it needs to trim its memory usage down.

Parameters

cap_bytes

Defines the maximum size the cache is allowed to reach before it starts trimming least-recently-used objects.

Definition at line 440 of file glutils.c.

glutils_debug_pop()

static inline void glutils_debug_pop ( void  )

static

If _LACF_RENDER_DEBUG is enabled, this compiles to a call to glPopDebugGroup(). You should use this in combination with glutils_debug_push(), set up debug groups for your rendering code.

See also

_LACF_RENDER_DEBUG

glutils_debug_push()

glPopDebugGroup()

Definition at line 601 of file glutils.h.

glutils_debug_push()

static inline void glutils_debug_push ( GLuint  msgid, const char *  format,   ...  )

static

If _LACF_RENDER_DEBUG is enabled, this compiles to a function which calls glPushDebugGroup() for draw call debugging. The source of the message is always GL_DEBUG_SOURCE_APPLICATION.

You must pair this call with a subsequent call to glutils_debug_pop() to close out the debug group.

Parameters

msgid	The message ID that will be passed in the second argument of glPushDebugGroup().
format	A printf-style format string, which will be used to dynamically control the message for the glPushDebugGroup() function. The remainder of the variadic arguments must match to the format specifiers.

See also

_LACF_RENDER_DEBUG

glutils_debug_pop()

glPushDebugGroup()

Definition at line 593 of file glutils.h.

glutils_destroy_lines()

void glutils_destroy_lines

(

glutils_lines_t *

lines

)

Deprecated:

The glutils_lines_t functionality is deprecated, as it relies on legacy GL_LINE_STRIP functionality of the OpenGL driver. See glutils_nl_t for a modern replacement.

Destroys a glutils_lines_t object which you have previously initialized using glutils_init_3D_lines().

Definition at line 742 of file glutils.c.

glutils_destroy_quads()

void glutils_destroy_quads

(

glutils_quads_t *

quads

)

Destroys a glutils_quads_t object, which was previously initialized using glutils_init_2D_quads() or glutils_init_3D_quads(). This releases all memory resources used by the object.

Definition at line 313 of file glutils.c.

glutils_disable_all_client_state()

void glutils_disable_all_client_state

(

void

)

Kills all OpenGL client state arrays. Call this before enabling the OpenGL client arrays you will need to draw, as otherwise you don't know if some other plugin left them in some misconfigured state.

Deprecated:

This function shouldn't be used for modern OpenGL contexts, as it uses the deprecated glDisableClientState() GL function.

Definition at line 128 of file glutils.c.

glutils_disable_all_vtx_attrs()

void glutils_disable_all_vtx_attrs

(

void

)

Disables all (but at most 32) vertex attribute arrays. This should be used to make sure all OpenGL state is clean at the start of an X-Plane draw callback when using shared vertex array objects.

Deprecated:

This function shouldn't be used for modern OpenGL contexts. You should only disable vertex attributes you've previously enabled.

Definition at line 158 of file glutils.c.

glutils_disable_vtx_attr_ptr()

static void glutils_disable_vtx_attr_ptr ( GLint  index )

static

Disables the vertex attribute array at index by calling glDisableVertexAttribArray(), but only if index is NOT -1. See glutils_enable_vtx_attr_ptr() for more information.

See also

glutils_enable_vtx_attr_ptr()

glDisableVertexAttribArray()

Definition at line 649 of file glutils.h.

glutils_draw_lines()

void glutils_draw_lines	(	glutils_lines_t *	lines,
		GLint	prog
	)

Deprecated:

The glutils_lines_t functionality is deprecated, as it relies on legacy GL_LINE_STRIP functionality of the OpenGL driver. See glutils_nl_t for a modern replacement.

Draws a glutils_lines_t object, using a custom shader program.

Parameters

lines	The glutils_lines_t object which you've previously initialized using glutils_init_3D_lines().
prog	A compiled and linked shader program, which will be used for the rendering. This must not be 0. See glutils_draw_quads() for more information on the structuring requirements for the program.

See also

glutils_draw_quads()

Definition at line 727 of file glutils.c.

glutils_draw_quads()

void glutils_draw_quads	(	glutils_quads_t *	quads,
		GLint	prog
	)

Renders a previously initialized glutils_quads_t object.

Parameters

quads

The quads object to be rendered.

prog

A compiled and linked OpenGL shader program, which will be used for the render. You are free to structure the fragment shader as you desire. The vertex shader, however, should follow these rules: vtx_pos: this input attribute receives a vec3 for each vertex in the quad. For quads initialized using glutils_init_2D_quads(), the data is still vec3s, but the Z coordinate will always be zero. vtx_tex0: this input attribute receives a vec2 for each vertex's UV coordinate. If you didn't provide UV coordinates in the quads init call, this vec2 will simply be (0,0) for all vertices and need not be declared in the shader.

Definition at line 387 of file glutils.c.

glutils_enable_vtx_attr_ptr()

static void glutils_enable_vtx_attr_ptr ( GLint  index, GLint  size, GLenum  type, GLboolean  normalized, size_t  stride, size_t  offset  )

static

A wrapper for glEnableVertexAttribArray() and glVertexAttribPointer(). In addition to performing both operations at the same time, this only gets executed if index is NOT -1, indicating that the shader program you are setting up the inputs for actually does take the input.

Parameters

index

The vertex attribute array index to enable. If this is -1, this function turns into a no-op. This happens, when the shader program doesn't actually use the input you are attempting to bind (glGetAttribLocation() returns this for non-existent attributes).

The remainder of the arguments are passed on as-is to glVertexAttribPointer().

See also

glEnableVertexAttribArray()

glVertexAttribPointer()

Definition at line 631 of file glutils.h.

glutils_init_2D_quads_impl()

void glutils_init_2D_quads_impl	(	glutils_quads_t *	quads,
		const char *	filename,
		int	line,
		const vect2_t *	p,
		const vect2_t *	t,
		size_t	num_pts
	)

Implementation of the glutils_init_2D_quads() macro. Don't call directly.

Definition at line 209 of file glutils.c.

glutils_init_3D_lines_impl()

void glutils_init_3D_lines_impl	(	glutils_lines_t *	lines,
		const char *	filename,
		int	line,
		const vect3_t *	p,
		size_t	num_pts
	)

Deprecated:

The glutils_lines_t functionality is deprecated, as it relies on legacy GL_LINE_STRIP functionality of the OpenGL driver. See glutils_nl_t for a modern replacement.

Implementation of the glutils_init_3D_lines() macro. Don't call directly.

Definition at line 666 of file glutils.c.

glutils_init_3D_quads_impl()

void glutils_init_3D_quads_impl	(	glutils_quads_t *	quads,
		const char *	filename,
		int	line,
		const vect3_t *	p,
		const vect2_t *	t,
		size_t	num_pts
	)

Implementation of the glutils_init_3D_quads() macro. Don't call directly.

Definition at line 239 of file glutils.c.

glutils_make_quads_IBO()

GLuint glutils_make_quads_IBO

(

size_t

num_vtx

)

This function is a shorthand for creating an index buffer to triangulate an old-style GL_QUADS object (which isn't supported in modern OpenGL anymore). The quad is triangulated in this order: p0-p1-p2 & p0-p2-p3. The IBO is constructed for quads composed num_vtx vertices. This number must be a multiple of 4.

Returns

The object number of the index buffer object in the OpenGL context.

Definition at line 176 of file glutils.c.

glutils_nl_alloc_2D()

glutils_nl_t * glutils_nl_alloc_2D	(	const vec2 *	pts,
		size_t	num_pts
	)

Same as glutils_nl_alloc_3D(), but expects 2D vertex data, with only X and Y coordinates. While drawing, this still emits 3D vertex data, but the Z coordinate is always set to 0.

See also

glutils_nl_t

Definition at line 1144 of file glutils.c.

glutils_nl_alloc_3D()

glutils_nl_t * glutils_nl_alloc_3D	(	const vec3 *	pts,
		size_t	num_pts
	)

Allocates a "new lines" glutils_nl_t object. This can be used to emulate the obsolete GL_LINES drawing type in legacy OpenGL, but only using OpenGL core features and with support for the fully programmable shader pipeline.

Parameters

pts	The 3D points to pass to the shader as vertex input.
num_pts	Number of points in the pts argument. This must be an even number. The line segments are drawn disconnected, so rather than drawing as a single continuous line, each pair of points is treated as a single line segment.

Returns

An initialized glutils_nl_t which is ready for drawing. Use glutils_nl_free() to release the vertices and their associated memory resources.

See also

glutils_nl_t

Definition at line 1179 of file glutils.c.

glutils_nl_draw()

void glutils_nl_draw	(	glutils_nl_t *	nl,
		float	width,
		GLuint	prog
	)

Renders a glutils_nl_t object.

Parameters

nl	Lines object previously created using glutils_nl_alloc_2D() or glutils_nl_alloc_3D().
width	The width of the line in pixels.
prog	A compiled and linked OpenGL program object. This may NOT be zero. See below for details on how this program must be constructed.

The shader program passed must include a specially crafted vertex shader. libacfutils ships a file named nl.vert in its headers, which contains the functionality to emulate the fixed screen-sized pixel behavior of GL_LINES. To utilize this code, you should structure your vertex shader code approximately as follows:

#include "acfutils/nl.vert"
 
layout(location = 0) uniform mat4 pvm;
 
void
main(void)
{
    gl_Position = nl_vert_main(pvm);
}

The vertex shader should call the nl_vert_main function with the pre-multiplied projection-view-model matrix of your rendering, and use its output for the gl_Position output of the vertex shader.

The nl.vert code snippet utilizes two additional internal uniforms and 3 vertex inputs. These are auto-populated by glutils_nl_draw(), but you may want to customize their layout locations in the resulting shader program. With no customizations, the inputs occupy locations 0-2, and the uniforms locations 10-11. To override the base of these locations, define LACF_NL_VERT_INPUT_OFFSET to move the input location offset and LACF_NL_VERT_UNIFORM_OFFSET to move the uniform location offset.

The fragment shader is entirely under your control. You may use it to perform arbitrary painting within the fragments generated by the line.

Definition at line 1333 of file glutils.c.

glutils_nl_free()

void glutils_nl_free

(

glutils_nl_t *

nl

)

Frees all resources associated with a glutils_nl_t, which was previously returned from glutils_nl_alloc_2D() or glutils_nl_alloc_3D().

Definition at line 1241 of file glutils.c.

glutils_nsight_debugger_present()

bool_t glutils_nsight_debugger_present

(

void

)

Returns

B_TRUE if the Nvidia Nsight debugger is loaded in the appp.

Caveat: current only works on Linux.

Definition at line 1076 of file glutils.c.

glutils_png2gltexfmt()

bool_t glutils_png2gltexfmt	(	int	png_color_type,
		int	png_bit_depth,
		GLint *	int_fmt,
		GLint *	fmt,
		GLint *	type
	)

Utility function to convert between libpng image color types and bit depths to a matching OpenGL texture format, suitable for directly holding decompressed PNG image data. The purpose of this function is to allow easy loading of PNG images into OpenGL textures.

Parameters

png_color_type	The PNG image color type. Must be one of PNG_COLOR_TYPE_RGB or PNG_COLOR_TYPE_RGB_ALPHA. No other color type is supported and will result in an error return.
png_bit_depth	The PNG image bit depth. This must be 8. No other bit depth is supported and will result in an error return.
int_fmt	A mandatory return argument, which will be filled with an OpenGL texture data internal format which matches the PNG image color type and bit depth (e.g. GL_RGB).
fmt	A mandatory return argument, which will be filled with an OpenGL texture data format which matches the PNG image color type and bit depth (e.g. GL_RGB).
type	A mandatory return argument, which will be filled with an OpenGL texture data type which matches the PNG image color type and bit depth (e.g. GL_UNSIGNED_BYTE).

Returns

B_TRUE if the PNG color type and bit depth are supported and the int_fmt, fmt and type return arguments were filled with the correct information. If the input PNG color type or bit depth do not match a supported combination, B_FALSE is returned instead and int_fmt, fmt and type are left unmodified.

Definition at line 1416 of file glutils.c.

glutils_quads_inited()

static bool_t glutils_quads_inited ( const glutils_quads_t *  quads )

static

Returns

B_TRUE if the quads have been initialized. This basically just checks if the vertex buffer is non-zero, so to make sure this works correctly, you should statically zero-initialize any glutils_quads_t objects. In fact, just zero-initialize everything you create.

See also

glutils_quads_t

Definition at line 133 of file glutils.h.

glutils_reset_errors()

static void glutils_reset_errors ( void  )

static

Drains the OpenGL error stack by repeatedly calling glGetError() until no more errors remain. Use this for development debugging.

Definition at line 518 of file glutils.h.

glutils_sys_init()

void glutils_sys_init

(

void

)

Initializes the glutils module. Should be called before any other functions of glutils are used.

Definition at line 108 of file glutils.c.

glutils_texsz_alloc()

void glutils_texsz_alloc	(	const char *	token,
		const void *	instance,
		const char *	filename,
		int	line,
		GLenum	format,
		GLenum	type,
		unsigned	w,
		unsigned	h
	)

Implementation of the TEXSZ_ALLOC* macros. Do not call this directly, use the wrapper macros instead.

See also

TEXSZ_ALLOC()

TEXSZ_ALLOC_INSTANCE()

Definition at line 984 of file glutils.c.

glutils_texsz_alloc_bytes()

void glutils_texsz_alloc_bytes	(	const char *	token,
		const void *	instance,
		const char *	filename,
		int	line,
		int64_t	bytes
	)

Implementation of the TEXSZ_ALLOC_BYTES* macros. Do not call this directly, use the wrapper macros instead.

See also

TEXSZ_ALLOC_BYTES()

TEXSZ_ALLOC_BYTES_INSTANCE()

Definition at line 1014 of file glutils.c.

glutils_texsz_enum()

void glutils_texsz_enum	(	glutils_texsz_enum_cb_t	cb,
		void *	userinfo
	)

Walks the entire list of allocations. This is mostly useful for debugging and/or VRAM profiling.

Parameters

cb	Callback which will be called for every allocation in the system.
userinfo	Optional argument, which will be passed to the callback.

Definition at line 1052 of file glutils.c.

glutils_texsz_fini()

void glutils_texsz_fini

(

void

)

Shuts down the TEXSZ system. If you are using this system, you should call this after releasing all OpenGL resources, to check that no leaks have occurred. If any resource registered with the TEXZ system hasn't been properly freed, this will cause an assertion failure, with debug information about where the allocation took place.

For more information about the system, see TEXSZ_MK_TOKEN().

Definition at line 833 of file glutils.c.

glutils_texsz_free()

void glutils_texsz_free	(	const char *	token,
		const void *	instance,
		GLenum	format,
		GLenum	type,
		unsigned	w,
		unsigned	h
	)

Implementation of the TEXSZ_FREE* macros. Do not call this directly, use the wrapper macros instead.

See also

TEXSZ_FREE()

TEXSZ_FREE_INSTANCE()

Definition at line 1000 of file glutils.c.

glutils_texsz_free_bytes()

void glutils_texsz_free_bytes	(	const char *	token,
		const void *	instance,
		int64_t	bytes
	)

Implementation of the TEXSZ_FREE_BYTES* macros. Do not call this directly, use the wrapper macros instead.

See also

TEXSZ_FREE_BYTES()

TEXSZ_FREE_BYTES_INSTANCE()

Definition at line 1028 of file glutils.c.

glutils_texsz_get()

uint64_t glutils_texsz_get

(

void

)

Returns

The total amount of bytes tracked. Useful for estimating GPU memory load due to custom avionics code.

Definition at line 1039 of file glutils.c.

glutils_texsz_init()

void glutils_texsz_init

(

void

)

This is the initializer for the TEXSZ profiling facility in glutils. This facility helps you keep track of allocations and checks to make sure memory isn't leaked.

If you intend on using the TEXSZ system, you should call this function before making any buffer allocations or OpenGL object creation. This initializes the allocation tracker. After you are done, you should shut down the system using glutils_texsz_fini(). This checks to make sure all allocated resources have been properly released. If not, this will cause an assertion failure, with debug information about where the allocation took place.

For more information about the system, see TEXSZ_MK_TOKEN().

Definition at line 814 of file glutils.c.

glutils_texsz_inited()

bool_t glutils_texsz_inited

(

void

)

Returns

B_TRUE if the TEXSZ machinery has been initialized.

Definition at line 1066 of file glutils.c.

glutils_update_2D_quads_impl()

void glutils_update_2D_quads_impl	(	glutils_quads_t *	quads,
		const char *	filename,
		int	line,
		const vect2_t *	p,
		const vect2_t *	t,
		size_t	num_pts
	)

Implementation of the glutils_update_2D_quads() macro. Don't call directly.

Definition at line 225 of file glutils.c.

glutils_update_3D_quads_impl()

void glutils_update_3D_quads_impl	(	glutils_quads_t *	quads,
		const char *	filename,
		int	line,
		const vect3_t *	p,
		const vect2_t *	t,
		size_t	num_pts
	)

Implementation of the glutils_update_3D_quads() macro. Don't call directly.

Definition at line 270 of file glutils.c.

glutils_vp2pvm()

void glutils_vp2pvm

(

GLfloat

pvm[16]

)

Utility function, which extracts the current viewport setting in the OpenGL context and creates an orthographic projection matrix, which will provide a 1:1 correspondence to the pixels of the viewport.

Parameters

pvm	Mandatory return argument, which will be filled with the resultant projection matrix ("pvm" = projection-view-model matrix).

Definition at line 762 of file glutils.c.