public interface EGLSpec


Interface for accessing various EGL facilities independent of EGL versions. That is each EGL version implements this specification.

EGLSpec is not thread safe and is up to the caller of these methods to guarantee thread safety.

Summary

Public fields

default static final @NonNull EGLSpec

Public methods

abstract int
eglClientWaitSyncKHR(
    @NonNull EGLSyncKHR sync,
    int flags,
    long timeoutNanos
)

Blocks the calling thread until the specified sync object is signalled or until timeoutNanos nanoseconds have passed.

abstract @NonNull EGLContext

Create an EGLContext with the default display.

abstract EGLImageKHR

Creates an EGLImage from the provided HardwareBuffer.

abstract @NonNull EGLSurface
eglCreatePBufferSurface(
    @NonNull EGLConfig config,
    EGLConfigAttributes configAttributes
)

Create a Pixel Buffer surface with the corresponding EGLConfigAttributes.

abstract EGLSyncKHR
eglCreateSyncKHR(int type, EGLConfigAttributes attributes)

Creates a sync object of the specified type associated with the specified display, and returns a handle to the new object.

abstract @NonNull EGLSurface
eglCreateWindowSurface(
    @NonNull EGLConfig config,
    @NonNull Surface surface,
    EGLConfigAttributes configAttributes
)

Creates an on screen EGL window surface from the given Surface and returns a handle to it.

abstract void

Destroy the given EGLContext generated in eglCreateContext

abstract boolean

Destroy the given EGLImageKHR instance.

abstract boolean

Destroys an EGL surface.

abstract boolean

Destroys the given sync object associated with the specified display

abstract @NonNull EGLSurface

Return the current surface used for drawing pixels.

abstract @NonNull EGLSurface

Return the current surface used for reading or copying pixels.

abstract int

Returns the error of the last called EGL function in the current thread.

abstract boolean
eglGetSyncAttribKHR(
    @NonNull EGLSyncKHR sync,
    int attribute,
    @NonNull int[] value,
    int offset
)

Query attributes of the provided sync object.

abstract @NonNull EGLVersion

Initialize the EGL implementation and return the major and minor version of the EGL implementation through EGLVersion.

abstract boolean
eglMakeCurrent(
    @NonNull EGLContext context,
    @NonNull EGLSurface drawSurface,
    @NonNull EGLSurface readSurface
)

Binds the current context to the given draw and read surfaces.

abstract @NonNull String
eglQueryString(int nameId)

Query for the capabilities associated with the given eglDisplay.

abstract boolean
eglQuerySurface(
    @NonNull EGLSurface surface,
    int attribute,
    @NonNull int[] result,
    int offset
)

Query the EGL attributes of the provided surface

abstract boolean

Post EGL surface color buffer to a native window

default @NonNull String

Convenience method to obtain the corresponding error string from the error code obtained from EGLSpec.eglGetError

default static final @NonNull String
getStatusString(int error)

Return a string representation of the corresponding EGL status code.

abstract EGLConfig

Load a corresponding EGLConfig from the provided EGLConfigAttributes If the EGLConfig could not be loaded, null is returned

Public fields

V14

default static final @NonNull EGLSpec V14

Public methods

eglClientWaitSyncKHR

Added in 1.0.0-beta01
abstract int eglClientWaitSyncKHR(
    @NonNull EGLSyncKHR sync,
    int flags,
    long timeoutNanos
)

Blocks the calling thread until the specified sync object is signalled or until timeoutNanos nanoseconds have passed. More than one eglClientWaitSyncKHR may be outstanding on the same sync at any given time. When there are multiple threads blocked on the same sync and the sync object has signalled, all such threads are released, but the order in which they are released is not defined.

If the value of timeoutNanos is zero, then eglClientWaitSyncKHR simply tests the current status of sync. If the value of timeoutNanos is the special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not time out. For all other values, timeoutNanos is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond.

eglClientWaitSyncKHR returns one of three status values describing the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR indicates that the specified timeout period expired before sync was signalled, or if timeoutNanos is zero, indicates that sync is not signaled. A return value of EGL_CONDITION_SATISFIED_KHR indicates that sync was signaled before the timeout expired, which includes the case when sync was already signaled when eglClientWaitSyncKHR was called. If an error occurs then an error is generated and EGL_FALSE is returned.

If the sync object being blocked upon will not be signaled in finite time (for example by an associated fence command issued previously, but not yet flushed to the graphics pipeline), then eglClientWaitSyncKHR may wait forever. To help prevent this behavior, if the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR is set on the flags parameter and the sync is unsignaled when eglClientWaitSyncKHR is called, then the equivalent flush will be performed for the current EGL context before blocking on sync. If no context is current bound for the API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is ignored.

Parameters
@NonNull EGLSyncKHR sync

EGLSyncKHR object to wait on

int flags

Optional flags to provide to handle flushing of pending commands

long timeoutNanos

Optional timeout value to wait before this method returns, measured in nanoseconds. This value is always consumed as an unsigned long value so even negative values will be converted to their unsigned equivalent.

Returns
int

Result code indicating the status of the wait request. Either EGL_CONDITION_SATISFIED_KHR, if the sync did signal within the specified timeout, EGL_TIMEOUT_EXPIRED_KHR if the sync did not signal within the specified timeout, or EGL_FALSE if an error occurs.

eglCreateContext

Added in 1.0.0-beta01
abstract @NonNull EGLContext eglCreateContext(@NonNull EGLConfig config)

Create an EGLContext with the default display. If createContext fails to create a rendering context, EGL_NO_CONTEXT is returned

Parameters
@NonNull EGLConfig config

EGLConfig used to create the EGLContext

eglCreateImageFromHardwareBuffer

Added in 1.0.0-beta01
@RequiresApi(value = 26)
abstract EGLImageKHR eglCreateImageFromHardwareBuffer(@NonNull HardwareBuffer hardwareBuffer)

Creates an EGLImage from the provided HardwareBuffer. This handles internally creating an EGLClientBuffer and an EGLImageKHR from the client buffer.

When this EGLImageKHR instance is no longer necessary, consumers should be sure to call the corresponding method eglDestroyImageKHR to deallocate the resource.

Parameters
@NonNull HardwareBuffer hardwareBuffer

Backing HardwareBuffer for the generated EGLImage instance

Returns
EGLImageKHR

an EGLImageKHR instance representing the EGLImageKHR created from the HardwareBuffer. Because this is created internally through EGL's eglCreateImageKR method, this has the KHR suffix.

This can return null if the EGL_ANDROID_image_native_buffer and EGL_KHR_image_base extensions are not supported or if allocation of the buffer fails.

See www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt

eglCreatePBufferSurface

Added in 1.0.0-beta01
abstract @NonNull EGLSurface eglCreatePBufferSurface(
    @NonNull EGLConfig config,
    EGLConfigAttributes configAttributes
)

Create a Pixel Buffer surface with the corresponding EGLConfigAttributes. Accepted attributes are defined as part of the OpenGL specification here: https://www.khronos.org/registry/EGL/sdk/docs/man/html/eglCreatePbufferSurface.xhtml

If a pixel buffer surface could not be created, EGL14.EGL_NO_SURFACE is returned.

Parameters
@NonNull EGLConfig config

Specifies the EGL Frame buffer configuration that defines the frame buffer resource available to the surface

EGLConfigAttributes configAttributes

Optional list of attributes for the pixel buffer surface

eglCreateSyncKHR

Added in 1.0.0-beta01
abstract EGLSyncKHR eglCreateSyncKHR(int type, EGLConfigAttributes attributes)

Creates a sync object of the specified type associated with the specified display, and returns a handle to the new object. The configuration of the returned EGLSyncKHR object is specified by the provided attributes.

Consumers should ensure that the EGL_KHR_fence_sync EGL extension is supported before invoking this method otherwise a null EGLSyncFenceKHR object is returned.

When the EGLSyncKHR instance is no longer necessary, consumers are encouraged to call eglDestroySyncKHR to deallocate this resource.

See: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_fence_sync.txt

Parameters
int type

Indicates the type of sync object that is returned

EGLConfigAttributes attributes

Specifies the configuration of the sync object returned

Returns
EGLSyncKHR

the EGLSyncKHR object to be used as a fence or null if this extension is not supported

eglCreateWindowSurface

Added in 1.0.0-beta01
abstract @NonNull EGLSurface eglCreateWindowSurface(
    @NonNull EGLConfig config,
    @NonNull Surface surface,
    EGLConfigAttributes configAttributes
)

Creates an on screen EGL window surface from the given Surface and returns a handle to it.

See https://khronos.org/registry/EGL/sdk/docs/man/html/eglCreateWindowSurface.xhtml

Parameters
@NonNull EGLConfig config

Specifies the EGL frame buffer configuration that defines the frame buffer resource available to the surface

@NonNull Surface surface

Android surface to consume rendered content

EGLConfigAttributes configAttributes

Optional list of attributes for the specified surface

eglDestroyContext

Added in 1.0.0-beta01
abstract void eglDestroyContext(@NonNull EGLContext eglContext)

Destroy the given EGLContext generated in eglCreateContext

See https://khronos.org/registry/EGL/sdk/docs/man/html/eglDestroyContext.xhtml

Parameters
@NonNull EGLContext eglContext

EGL rendering context to be destroyed

eglDestroyImageKHR

Added in 1.0.0-beta01
abstract boolean eglDestroyImageKHR(@NonNull EGLImageKHR image)

Destroy the given EGLImageKHR instance. Once destroyed, the image may not be used to create any additional EGLImageKHR target resources within any client API contexts, although existing EGLImageKHR siblings may continue to be used. true is returned if DestroyImageKHR succeeds, false indicates failure. This can return false if the corresponding EGLContext is not valid.

See: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_image_base.txt

Parameters
@NonNull EGLImageKHR image

EGLImageKHR to be destroyed

Returns
boolean

true if the destruction of the EGLImageKHR object was successful, false otherwise

eglDestroySurface

Added in 1.0.0-beta01
abstract boolean eglDestroySurface(@NonNull EGLSurface surface)

Destroys an EGL surface.

If the EGL surface is not current to any thread, eglDestroySurface destroys it immediately. Otherwise, surface is destroyed when it becomes not current to any thread. Furthermore, resources associated with a pbuffer surface are not released until all color buffers of that pbuffer bound to a texture object have been released. Deferral of surface destruction would still return true as deferral does not indicate a failure condition

Returns
boolean

true if destruction of the EGLSurface was successful, false otherwise

eglDestroySyncKHR

Added in 1.0.0-beta01
abstract boolean eglDestroySyncKHR(@NonNull EGLSyncKHR sync)

Destroys the given sync object associated with the specified display

Consumers should ensure that the EGL_KHR_fence_sync EGL extension is supported before invoking this method otherwise a null EGLSyncFenceKHR object is returned. See: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_fence_sync.txt

Parameters
@NonNull EGLSyncKHR sync

Fence object to be destroyed

Returns
boolean

true if the EGLSyncKHR object was destroyed successfully false otherwise. This can return false if the sync object is not a valid sync object for the provided display or if the display provided in this method does not match the display used to create this sync in eglCreateSyncKHR.

eglGetCurrentDrawSurface

Added in 1.0.0-beta01
abstract @NonNull EGLSurface eglGetCurrentDrawSurface()

Return the current surface used for drawing pixels. If no context is current, EGL14.EGL_NO_SURFACE is returned.

eglGetCurrentReadSurface

Added in 1.0.0-beta01
abstract @NonNull EGLSurface eglGetCurrentReadSurface()

Return the current surface used for reading or copying pixels. If no context is current, EGL14.EGL_NO_SURFACE is returned

eglGetError

Added in 1.0.0-beta01
abstract int eglGetError()

Returns the error of the last called EGL function in the current thread. Initially, the error is set to EGL_SUCCESS. When an EGL function could potentially generate several different errors (for example, when passed both a bad attribute name, and a bad attribute value for a legal attribute name), the implementation may choose to generate any one of the applicable errors.

See https://khronos.org/registry/EGL/sdk/docs/man/html/eglGetError.xhtml for more information and error codes that could potentially be returned

eglGetSyncAttribKHR

Added in 1.0.0-beta01
abstract boolean eglGetSyncAttribKHR(
    @NonNull EGLSyncKHR sync,
    int attribute,
    @NonNull int[] value,
    int offset
)

Query attributes of the provided sync object. Accepted attributes to query depend on the type of sync object. If no errors are generated, this returns true and the value of the queried attribute is stored in the value array at the offset position. If this method returns false, the provided value array is unmodified.

See: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_fence_sync.txt

Parameters
@NonNull EGLSyncKHR sync

EGLSyncKHR object to query attributes

int attribute

Corresponding EGLSyncKHR attribute to query on sync

@NonNull int[] value

Integer array used to store the result of the query

int offset

Index within the value array to store the result of the attribute query

Returns
boolean

true if the attribute was queried successfully, false otherwise. Failure cases include attempting to call this method on an invalid sync object, or the display provided not matching the display that was used to create this sync object. Additionally if the queried attribute is not supported for the sync object, false is returned.

eglInitialize

Added in 1.0.0-beta01
abstract @NonNull EGLVersion eglInitialize()

Initialize the EGL implementation and return the major and minor version of the EGL implementation through EGLVersion. If initialization fails, this returns EGLVersion.Unknown

eglMakeCurrent

Added in 1.0.0-beta01
abstract boolean eglMakeCurrent(
    @NonNull EGLContext context,
    @NonNull EGLSurface drawSurface,
    @NonNull EGLSurface readSurface
)

Binds the current context to the given draw and read surfaces. The draw surface is used for all operations except for any pixel data read back or copy operations which are taken from the read surface.

The same EGLSurface may be specified for both draw and read surfaces.

See https://www.khronos.org/registry/EGL/sdk/docs/man/html/eglMakeCurrent.xhtml for more information

Parameters
@NonNull EGLSurface drawSurface

EGLSurface to draw pixels into.

@NonNull EGLSurface readSurface

EGLSurface used for read/copy operations.

eglQueryString

Added in 1.0.0-beta01
abstract @NonNull String eglQueryString(int nameId)

Query for the capabilities associated with the given eglDisplay. The result contains a space separated list of the capabilities.

Parameters
int nameId

identifier for the EGL string to query

eglQuerySurface

Added in 1.0.0-beta01
abstract boolean eglQuerySurface(
    @NonNull EGLSurface surface,
    int attribute,
    @NonNull int[] result,
    int offset
)

Query the EGL attributes of the provided surface

Parameters
@NonNull EGLSurface surface

EGLSurface to be queried

int attribute

EGL attribute to query on the given EGL Surface

@NonNull int[] result

Int array to store the result of the query

int offset

Index within result to store the value of the queried attribute

Returns
boolean

true if the query was completed successfully, false otherwise. If the query fails, result is unmodified

eglSwapBuffers

Added in 1.0.0-beta01
abstract boolean eglSwapBuffers(@NonNull EGLSurface surface)

Post EGL surface color buffer to a native window

See https://khronos.org/registry/EGL/sdk/docs/man/html/eglSwapBuffers.xhtml

Parameters
@NonNull EGLSurface surface

Specifies the EGL drawing surface whose buffers are to be swapped

Returns
boolean

true if swapping of buffers succeeds, false otherwise

getErrorMessage

Added in 1.0.0-beta01
default @NonNull String getErrorMessage()

Convenience method to obtain the corresponding error string from the error code obtained from EGLSpec.eglGetError

getStatusString

Added in 1.0.0-beta01
default static final @NonNull String getStatusString(int error)

Return a string representation of the corresponding EGL status code. If the provided error value is not an EGL status code, the hex representation is returned instead

loadConfig

Added in 1.0.0-beta01
abstract EGLConfig loadConfig(@NonNull EGLConfigAttributes configAttributes)

Load a corresponding EGLConfig from the provided EGLConfigAttributes If the EGLConfig could not be loaded, null is returned

Parameters
@NonNull EGLConfigAttributes configAttributes

Desired EGLConfigAttributes to create an EGLConfig

Returns
EGLConfig

the EGLConfig with the provided EGLConfigAttributes or null if an EGLConfig could not be created with the specified attributes