overview

Documentation

Overview

ASurfaceTexture API overview.

Documents the Android ASurfaceTexture lifecycle and the methods provided by the ndk/surfacetexture package. ASurfaceTexture streams image frames from an Android Surface into an OpenGL ES texture (GL_TEXTURE_EXTERNAL_OES), enabling GPU-accelerated rendering of camera preview, video playback, or any Surface-backed producer.

The NDK ASurfaceTexture handle is obtained from a Java SurfaceTexture object via JNI. There is no pure-NDK constructor. The typical pattern is:

Java side:
  SurfaceTexture st = new SurfaceTexture(/* texName */ 0);
  st.detachFromGLContext();   // detach so native can re-attach

JNI bridge:
  ASurfaceTexture* ast = ASurfaceTexture_fromSurfaceTexture(env, javaST);

Go side:
  // Wrap the raw *ASurfaceTexture into surfacetexture.SurfaceTexture
  st := surfacetexture.NewSurfaceTextureFromPointer(rawPtr)

Because the SurfaceTexture handle requires a JNI environment and a Java SurfaceTexture jobject, this example documents the workflow and prints the API surface rather than calling the methods directly.

GL texture workflow:

1. Create GL_TEXTURE_EXTERNAL_OES texture: glGenTextures(1, &texName) glBindTexture(GL_TEXTURE_EXTERNAL_OES, texName)

2. Attach the SurfaceTexture to the GL context: st.AttachToGLContext(texName)

3. When a new frame arrives (via onFrameAvailable callback): st.UpdateTexImage()

4. Retrieve the 4x4 texture transform matrix for the shader: var mtx [16]float32 st.TransformMatrix(&mtx[0])

5. Retrieve the frame timestamp (nanoseconds): ts := st.Timestamp()

6. Render using the external texture with the transform matrix applied in the fragment shader via samplerExternalOES.

7. When switching GL contexts or done: st.DetachFromGLContext()

8. Release the SurfaceTexture: st.Close()

Fragment shader for external textures:

#extension GL_OES_EGL_image_external : require
precision mediump float;
varying vec2 vTexCoord;
uniform samplerExternalOES uTexture;
uniform mat4 uTexMatrix;
void main() {
    vec2 tc = (uTexMatrix * vec4(vTexCoord, 0.0, 1.0)).xy;
    gl_FragColor = texture2D(uTexture, tc);
}

Prerequisites:

• Android device with API level 28+ (ASurfaceTexture was added in API 28).
• A Java SurfaceTexture obtained from the application's Java layer.
• A current EGL context with GL_OES_EGL_image_external support.

This program must run on an Android device.