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 ErrorReset1, ErrorReset2 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 in : GLApi

The API.

context in : 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 in, using the specified context in for function pointer retrieval.

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

Public / Methods

Error​Reset

2 overloads


public method ErrorReset1 → ()

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.


public method ErrorReset2 → (1)

source in : string

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.

Error​Throw


public method ErrorThrow → (2)

source in : string

The error source tag.

functionName in : 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.

Extension


[Pure]
public method Extension → (1)

name in : 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 in : IntPtr

The handle value.

returns → int32

The object name.

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

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.

Version


[Pure]
public method Version → (2)

major in : int32

The major API version.

minor in : 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

Wrap

12 overloads


public method Wrap1 → (1)

in : float32

The value to wrap.

returns → float32 [ ]

The wrapping array.

Wraps the given value in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapFloat


public method Wrap2 → (2)

in : float32

The value to wrap.

in : float32

The value to wrap.

returns → float32 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapFloat


public method Wrap3 → (3)

in : float32

The value to wrap.

in : float32

The value to wrap.

in : float32

The value to wrap.

returns → float32 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapFloat


public method Wrap4 → (4)

in : float32

The value to wrap.

in : float32

The value to wrap.

in : float32

The value to wrap.

in : float32

The value to wrap.

returns → float32 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapFloat


public method Wrap5 → (1)

in : int32

The value to wrap.

returns → int32 [ ]

The wrapping array.

Wraps the given value in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapInt


public method Wrap6 → (2)

in : int32

The value to wrap.

in : int32

The value to wrap.

returns → int32 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapInt


public method Wrap7 → (3)

in : int32

The value to wrap.

in : int32

The value to wrap.

in : int32

The value to wrap.

returns → int32 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapInt


public method Wrap8 → (4)

in : int32

The value to wrap.

in : int32

The value to wrap.

in : int32

The value to wrap.

in : int32

The value to wrap.

returns → int32 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapInt


public method Wrap9 → (1)

in : int64

The value to wrap.

returns → int64 [ ]

The wrapping array.

Wraps the given value in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapLong


public method Wrap10 → (2)

in : int64

The value to wrap.

in : int64

The value to wrap.

returns → int64 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapLong


public method Wrap11 → (3)

in : int64

The value to wrap.

in : int64

The value to wrap.

in : int64

The value to wrap.

returns → int64 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapLong


public method Wrap12 → (4)

in : int64

The value to wrap.

in : int64

The value to wrap.

in : int64

The value to wrap.

in : int64

The value to wrap.

returns → int64 [ ]

The wrapping array.

Wraps the given values in an array.

The returned array will remain valid until a Wrap* method is called again.

See also

GLBase.WrapLong

Wrap​Float


public method WrapFloat → (1)

length opt : int32 = 1

[>=1]
The wrapper array length.

returns → float32 [ ]

The wrapper array with undefined contents.

Returns a wrapper array.

The returned array will remain valid until a Wrap* method is called again.

Wrap​Int


public method WrapInt → (1)

length opt : int32 = 1

[>=1]
The wrapper array length.

returns → int32 [ ]

The wrapper array with undefined contents.

Returns a wrapper array.

The returned array will remain valid until a Wrap* method is called again.

Wrap​Long


public method WrapLong → (1)

length opt : int32 = 1

[>=1]
The wrapper array length.

returns → int64 [ ]

The wrapper array with undefined contents.

Returns a wrapper array.

The returned array will remain valid until a Wrap* method is called again.

Public / Attributes

Context


public attribute Context → (get)

value : GLBase

The GLBase object or null.

The GLBase object that represents the native API for managing GL contexts.

Extensions


public attribute Extensions → (get)

value : ISortedSetConst<string>

[not-null]
The extension names.

The supported API extensions.

This set represents the extension names as they have been reported from the underlying GL. It may contain extensions for which the corresponding public attribute is false. This may happen if one or more extension function pointers have not been found.

This property may be accessed when there is no current GL context.

See also

GLBase.Extension

Protected / Constructors

GLBase


protected constructor GLBase → (3)

name in : string

[not-empty]
Human-readable name for this native library.

context in : GLBase own

Optional GLBase object to use for retrieving function pointers.

versionBase in : Vec2I

The base API version.

Creates a new instance of GLBase.

Protected / Methods

Error​Fetch


protected abstract method ErrorFetch → ()

returns → int32

The error code or 0 if there are no more errors.

Polls the next error.

Extension​Check


[Pure]
protected abstract method ExtensionCheck → (1)

name in : string

The extension name.

returns → bool

true if the extensions has been loaded,
false if the extensions has not been loaded.

Checks if the given extension has been loaded by this wrapper.

Has

2 overloads


protected method Has1 → (1)

extension in : string

The extension name.

returns → bool

true if the given extension in is available,
false if it is not available.

Checks if the given extension is present, i.e. whether it is contained in Extensions.

This is a convenience method intended for use by implementations of NativeLibrary.InitializeFunctionPointers.

See also

GLBase.Extension


protected method Has2 → (2)

major in : int32

The major API version.

minor in : int32

The minor API version.

returns → bool

true if the given version is available,
false if it is not available.

Checks if the given API version is supported.

This is a convenience method intended for use by implementations of NativeLibrary.InitializeFunctionPointers.

See also

GLBase.Version

Lookup​Extensions


[EmptyBody]
protected virtual method LookupExtensions → (1)

index in : int32

Zero-based index of this method call.

returns → string

The index in-th extension string or null to stop calling this method. Each extension string may contain zero or more extensions names, separated by whitespaces.

Returns the supported API extensions.

This method is called repeatedly during the first time the Extensions property is accessed or the Has1 method is called, until it returns null.

Lookup​Memory


[EmptyBody]
protected virtual method LookupMemory → ()

returns → int32

The video memory value to return.

Computes the amount of video memory to return via IVideoMemoryContainer.VideoMemory.

Lookup​Version


[EmptyBody]
protected virtual method LookupVersion → ()

returns → string

The API version string that contains a token in the form 'X.Y' or null if none.

Returns the supported API version.

This method is called once during the first time the Has2 method is called.

On​Error


protected virtual method OnError → (2)

source in : string

The error source tag that should be included when reporting unexpected GL errors or null iff the GL errors are expected.

error in : int32

The GL error code.

This method is called after at least one GL error has been encountered.

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.