Skip to main content

SpecsMediaGLTexture

Reference for SpecsMediaGLTexture, the SPECS NDK API that updates a caller-owned OpenGL ES texture from SpecsMediaBuffer video frames.

SpecsMediaGLTexture updates one caller-owned OpenGL ES texture from video frames carried in SpecsMediaBuffer, so decoded or captured video can be rendered by your own GL code without copying frames through CPU memory.

#include <SpecsMediaGLTexture.h>
target_link_libraries(myapp specs_media GLESv2 EGL)

SpecsMedia never creates, reallocates, resizes, or deletes the output texture—the caller owns the texture id, its storage and parameters, and the eventual glDeleteTextures() call.

Output modes

// Since: v1.3.0
typedef enum SpecsMediaGLTexture_OutputMode {
SPECS_MEDIA_GL_TEXTURE_OUTPUT_RGBA = 0, // convert to RGBA in a caller GL_TEXTURE_2D (default)
SPECS_MEDIA_GL_TEXTURE_OUTPUT_YUV_DIRECT = 1, // attach native image to a caller GL_TEXTURE_EXTERNAL_OES
} SpecsMediaGLTexture_OutputMode_t;
ModeRequired textureHow to sampleNotes
SPECS_MEDIA_GL_TEXTURE_OUTPUT_RGBAGL_TEXTURE_2D with already-allocated RGBA-compatible storageNormal sampler2DRecommended for most clients. Source and texture sizes may differ—the frame is scaled to the texture using full-frame normalized sampling. Alpha is written fully opaque. YUV is converted to R'G'B' with the source's color matrix and range (from the decoder's or player's video caps), or BT.601 limited range for buffers that don't record them.
SPECS_MEDIA_GL_TEXTURE_OUTPUT_YUV_DIRECTGL_TEXTURE_EXTERNAL_OESYUV-aware external-texture shader (for example GL_EXT_YUV_target, __samplerExternal2DY2YEXT)No RGBA conversion; direct access to the native media image. The buffer representation remains opaque.

Types

// Since: v1.3.0
typedef struct SpecsMediaGLTexture SpecsMediaGLTexture; // opaque

// Since: v1.3.0
typedef struct SpecsMediaGLTexture_CreateInfo {
SpecsMediaGLTexture_OutputMode_t outputMode; // use OUTPUT_RGBA unless you sample external YUV textures
uint32_t textureId; // non-zero, caller-owned, compatible with outputMode
} SpecsMediaGLTexture_CreateInfo_t;

// Since: v1.3.0
typedef struct SpecsMediaGLTexture_Info {
uint32_t textureId; // caller texture id supplied at creation
uint32_t textureTarget; // GL_TEXTURE_2D (RGBA) or GL_TEXTURE_EXTERNAL_OES (YUV_DIRECT)
uint32_t textureWidth; // RGBA: allocated texture width (after create); YUV_DIRECT: latest frame width
uint32_t textureHeight; // RGBA: allocated texture height (after create); YUV_DIRECT: latest frame height
uint32_t sourceWidth; // latest source buffer width (0 until first successful update)
uint32_t sourceHeight; // latest source buffer height (0 until first successful update)
uint64_t timestampNs; // latest source buffer timestamp in ns (0 until first successful update)
SpecsMediaGLTexture_OutputMode_t outputMode;
} SpecsMediaGLTexture_Info_t;

Functions

// Create an updater for a caller-owned texture. An EGL display + GL ES context
// must be current. *outTexture is written only on success.
// Returns BAD_ARGUMENT (invalid args or texture incompatible with outputMode),
// INVALID_STATE (no current context), UNSUPPORTED (mode not supported on this
// platform), or NOMEM.
// Since: v1.3.0
SpecsMedia_Result SpecsMediaGLTexture_create(
const SpecsMediaGLTexture_CreateInfo_t *createInfo,
SpecsMediaGLTexture **outTexture);

// Update the caller texture from a video SpecsMediaBuffer. The context used at
// create time must be current. The caller may release its buffer reference after
// this returns. On failure the previous contents remain valid.
// Returns BAD_ARGUMENT (NULL args), INVALID_STATE (wrong/no context, or texture
// not currently usable), UNSUPPORTED (buffer cannot be used for texture output),
// or GENERIC.
// Since: v1.3.0
SpecsMedia_Result SpecsMediaGLTexture_updateFromBuffer(
SpecsMediaGLTexture *texture, SpecsMediaBuffer *buffer);

// Query texture id/target, output and source dimensions, latest timestamp, mode.
// Since: v1.3.0
SpecsMedia_Result SpecsMediaGLTexture_getInfo(
const SpecsMediaGLTexture *texture, SpecsMediaGLTexture_Info_t *outInfo);

// Destroy the updater (does NOT delete the caller texture). Same context must be
// current. On success *texture is set to NULL; on failure it is left unchanged
// and ownership stays with the caller.
// Since: v1.3.0
SpecsMedia_Result SpecsMediaGLTexture_destroy(SpecsMediaGLTexture **texture);

The BAD_ARGUMENT, INVALID_STATE, UNSUPPORTED, NOMEM and GENERIC returns are the SPECSMEDIA_ERROR_* values of SpecsMedia_Result, listed in SpecsMedia result codes.

Update a texture from decoded frames

// With your EGL context current:
GLuint tex;
glGenTextures(1, &tex);
glBindTexture(GL_TEXTURE_2D, tex);
glTexStorage2D(GL_TEXTURE_2D, 1, GL_RGBA8, 1280, 720); // storage must exist before create()

SpecsMediaGLTexture_CreateInfo_t ci = {
.outputMode = SPECS_MEDIA_GL_TEXTURE_OUTPUT_RGBA,
.textureId = tex,
};
SpecsMediaGLTexture *glt = NULL;
if (SpecsMediaGLTexture_create(&ci, &glt) != SPECSMEDIA_SUCCESS) { /* handle */ }

// Per decoded frame (codec configured with OUTPUT_MEDIA_BUFFER):
SpecsMediaBuffer *buf = SpecsMediaCodec_getOutputMediaBuffer(codec, idx);
SpecsMediaGLTexture_updateFromBuffer(glt, buf);
SpecsMediaBuffer_release(&buf);
SpecsMediaCodec_releaseOutputBuffer(codec, idx);
// ... draw with `tex` bound as a sampler2D ...

// Teardown — destroy the updater before deleting the texture or the context.
SpecsMediaGLTexture_destroy(&glt);
glDeleteTextures(1, &tex);

GL state and threading

  • SpecsMediaGLTexture_updateFromBuffer() may bind GL objects internally but restores the state it modifies before returning: active texture, texture bindings on units it uses, draw/read framebuffer bindings, current program, vertex array, viewport, color write mask, and draw-affecting enables (scissor, blend, depth/stencil, cull, rasterizer-discard).
  • It does not call glFlush() / glFinish(); GL work submitted later on the same context observes normal command order.
  • The same EGL display and GL ES context used at create() must be current for updateFromBuffer() and destroy().
  • SpecsMediaGLTexture APIs are not thread-safe—serialize access to a given SpecsMediaGLTexture instance.