GLBase

Description

abstract class Tinman.Engine.API.GLBase

Derived from: NativeLibrary ^abstract
IVideoMemoryContainer
Extended by: EGL ^sealed
GLBaseWithDebug ^abstract
GLX ^sealed
WGL ^sealed

Abstract base class for NativeLibrary implementations that access a native GL-style API.

Public constants define enumeration items that may be passed to or returned from API commands. The documentation links to the API version and/or API extension that has introduced the enumeration item.
For example:
Public constant BLEND_SRC_ALPHA for API enumeration item GL_BLEND_SRC_ALPHA (32971), introduced by API version GL_VERSION_1_4 (i.e. OpenGL 1.4).

Public attributes of type bool are used to indicate the availability of those API extensions that can be accessed directly through the wrapper. The documentation links to the enumeration items and commands that are used by the API extension. The full list of available extensions may be queried via Extensions, individual extensions may be queried with Extension. API extensions that have no enumeration items and no commands are omitted from the wrapper.
For example:
Public attribute GL_NV_mesh_shader.

A GLBase subclass implements a specific minimum version of a GL-style API (for example OpenGL 4.1), which features are always available. Features of higher versions are treated like extensions via Version, using the special extension name {PREFIX}_VERSION_{X}_{Y}, where {PREFIX} is an implementation-specific name prefix (for example GL_ES) and {X} / {Y} are the major and minor API version. API extensions that have become obsolete by the minimum API version are omitted from the wrapper.
For example:
Public attribute GL_VERSION_4_6, indicating the availability of the OpenGL 4.6 API.

To avoid unnecessary clutter in the wrapper, identical enumeration items and commands are propagated through API extensions towards API versions, if possible. For enumeration items, the first possible action is performed: (1) the vendor tag (e.g. ARB, NV) is dropped, (2) the vendor tag is replaced with KHR, (3) the vendor tag is replaced with ARB, (4) the vendor tag is replaced with EXT. Commands may have an alias (defined by the Khronos XML API Registry): the wrapper then drops these commands and uses the alias instead.
For example:
Public attribute ALPHA8 for API enumeration item GL_ALPHA8 which has been propagated from GL_ALPHA8_EXT.
Public method ActiveTexture for API command glActiveTexture which is an alias of glActiveTextureARB.

Public methods represent the API commands, where method signatures closely model the command parameters, without imposing convenience layers dealing with marshalling or abstraction. Use the Wrap methods to pass per-reference arguments.

Calling an API command may generate zero or more errors, which must be reported by subclasses by implementing the ErrorFetch method. Use the ErrorReset¹, ErrorReset² and ErrorThrow methods to perform error handling.

The NativeLibrary.InitializeFunctionPointers method of subclasses must call the base method as the final statement, before returning.

Public / Constructors

Create

[OwnerReturn]
public static method Create → (3)

api ⁱⁿ : GLApi: The API flag.
context ⁱⁿ : GLBase ^own: [not-null]
The context.
plain ^opt : bool = false: Use a plain GL-wrapper (see Plain)?
returns → GLBase: The GLBase object or null if not available on this machine or platform.

Creates a GLBase object for the given api ⁱⁿ, using the specified context ⁱⁿ for function pointer retrieval.

This method requires that there is a current render context for the calling thread.

Public / Methods

ApiToVersion

[Pure]
public static method ApiToVersion → (1)

api ⁱⁿ : GLApi: The GLApi flags.
returns → Vec2I: The smallest GL API version (3.x for GLApi.OpenGLES or 4.x for GLApi.OpenGL) that covers the given flags.

Translates the given GLApi flags to conservative GL API version.

ErrorReset

_2 overloads

public method ErrorReset¹ → ()

returns → bool: true if no GL errors were present,
false if at least one GL error has been reported.

Resets all GL errors that have been recorded so far.

This method calls ErrorFetch repeatedly until it returns 0 and treats GL errors as expected (no error logging). When this method returns false, it might have called a Wrap* method.

See also: GLBase.ErrorThrow

public method ErrorReset² → (1)

source ⁱⁿ : string @ Tag: The error source tag to use for logging unexpected errors.
returns → bool: true if no GL errors were present,
false if at least one GL error has been reported.

Resets all GL errors that have been recorded so far.

This method calls ErrorFetch repeatedly until it returns 0 and treats GL errors as unexpected (with error logging) by the application. When this method returns false, it might have called a Wrap* method.

See also: GLBase.ErrorThrow

ErrorThrow

public method ErrorThrow → (2)

source ⁱⁿ : string @ Tag: The error source tag.
functionName ⁱⁿ : string: The GL function name to report on failure.

Throws an exception if the GL has recorded an error.

This method calls ErrorFetch repeatedly until it returns 0 and treats GL errors as unexpected by the application. If at least one call has returned a non-zero error value, an exception is thrown. Otherwise, it returns normally. When this method throws, it might have called a Wrap* method.

RenderException: If a non-zero error value has been recorded.

See also: GLBase.ErrorReset¹
GLBase.ErrorReset²

Extension

[Pure]
public method Extension → (1)

name ⁱⁿ : string: The extension name, see Extensions.
returns → int32: 0 : if the extension is not supported,
1 : if the extension is supported by the GL but not loaded by the wrapper,
2 : if the extension is supported by the GL and loaded by the wrapper.

Checks if the given extension is supported.

This method may be called when there is no current GL context.

Handle

[Pure]
public static method Handle → (1)

value ⁱⁿ : IntPtr: The handle value.
returns → int32: The object name.

Extracts the non-negative 32-bit integer object name from the given handle.

Limit

public method Limit → (2)

major ⁱⁿ : int32: The maximum API major version to use.
minor ⁱⁿ : int32: The maximum API minor version to use.

Puts this GL-wrapper in version-limited mode.

In version-limited mode, a GL-wrapper will report major ⁱⁿ / minor ⁱⁿ, or lower. This method may only be called before calling NativeLibrary.Initialize.

See also: GLBase.Plain

LogExtensions

public method LogExtensions → (2)

verbosity ^opt : LogVerbosity = LogVerbosity.Debug: The log verbosity to use.
logger ^opt : ILogger = null: The logger to use or null to use Logger.

Helper method that outputs a log message for each supported extension.

Plain

public method Plain → ()

Puts this GL-wrapper in plain mode.

In plain mode, a GL-wrapper will only load the base API version. It will not load any extensions. This method may only be called before calling NativeLibrary.Initialize.

See also: GLBase.Limit

Version

[Pure]
public method Version → (2)

major ⁱⁿ : int32: The major API version.
minor ⁱⁿ : int32: The minor API version.
returns → int32: 0 : if the version is not supported,
1 : if the version is supported by the GL but not loaded by the wrapper,
2 : if the version is supported by the GL and loaded by the wrapper.

Checks if the given API version is supported.

This method may be called when there is no current GL context.

See also: GLBase.Plain

VersionToApi

[Pure]
public static method VersionToApi → (1)

version ⁱⁿ : Vec2I: The GL API version: 3.x for GLApi.OpenGLES or 4.x for GLApi.OpenGL.
returns → GLApi: The GLApi flags, up to version ⁱⁿ (inclusive).

Translates the given GL API version to a GLApi value.

Wrap

_{12 overloads}

public method Wrap¹ → (1)

a ⁱⁿ : float32: The value to wrap.
returns → float32 [ ]: The wrapping array.

Wraps the given value in an array.