SurfaceTexture

SurfaceTexture

SurfaceTexture(singleBufferMode: Boolean)

Construct a new SurfaceTexture to stream images to a given OpenGL texture.

In single buffered mode the application is responsible for serializing access to the image content buffer. Each time the image content is to be updated, the releaseTexImage() method must be called before the image content producer takes ownership of the buffer. For example, when producing image content with the NDK ANativeWindow_lock and ANativeWindow_unlockAndPost functions, releaseTexImage() must be called before each ANativeWindow_lock, or that call will fail. When producing image content with OpenGL ES, releaseTexImage() must be called before the first OpenGL ES function call each frame.

Unlike SurfaceTexture(int,boolean), which takes an OpenGL texture object name, this constructor creates the SurfaceTexture in detached mode. A texture name must be passed in using attachToGLContext before calling releaseTexImage() and producing image content using OpenGL ES.

SurfaceTexture

SurfaceTexture(texName: Int)

Construct a new SurfaceTexture to stream images to a given OpenGL texture.

SurfaceTexture

SurfaceTexture(
    texName: Int, 
    singleBufferMode: Boolean)

Construct a new SurfaceTexture to stream images to a given OpenGL texture.

In single buffered mode the application is responsible for serializing access to the image content buffer. Each time the image content is to be updated, the releaseTexImage() method must be called before the image content producer takes ownership of the buffer. For example, when producing image content with the NDK ANativeWindow_lock and ANativeWindow_unlockAndPost functions, releaseTexImage() must be called before each ANativeWindow_lock, or that call will fail. When producing image content with OpenGL ES, releaseTexImage() must be called before the first OpenGL ES function call each frame.

attachToGLContext

open fun attachToGLContext(texName: Int): Unit

Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread. A new OpenGL ES texture object is created and populated with the SurfaceTexture image frame that was current at the time of the last call to detachFromGLContext. This new texture is bound to the GL_TEXTURE_EXTERNAL_OES texture target.

This can be used to access the SurfaceTexture image contents from multiple OpenGL ES contexts. Note, however, that the image contents are only accessible from one OpenGL ES context at a time.

detachFromGLContext

open fun detachFromGLContext(): Unit

Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object. This call must be made with the OpenGL ES context current on the calling thread. The OpenGL ES texture object will be deleted as a result of this call. After calling this method all calls to updateTexImage will throw an java.lang.IllegalStateException until a successful call to attachToGLContext is made.

This can be used to access the SurfaceTexture image contents from multiple OpenGL ES contexts. Note, however, that the image contents are only accessible from one OpenGL ES context at a time.

getDataSpace

open fun getDataSpace(): Int

Retrieve the dataspace associated with the texture image set by the most recent call to updateTexImage.

getTimestamp

open fun getTimestamp(): Long

Retrieve the timestamp associated with the texture image set by the most recent call to updateTexImage.

This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp should be unaffected by time-of-day adjustments. The specific meaning and zero point of the timestamp depends on the source providing images to the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot generally be compared across SurfaceTexture instances, or across multiple program invocations. It is mostly useful for determining time offsets between subsequent frames.

For camera sources, timestamps should be strictly monotonic. Timestamps from MediaPlayer sources may be reset when the playback position is set. For EGL and Vulkan producers, the timestamp is the desired present time set with the EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions.

getTransformMatrix

open fun getTransformMatrix(mtx: FloatArray!): Unit

Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to updateTexImage.

This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample that location from the texture. Sampling the texture outside of the range of this transform is undefined.

The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via the glLoadMatrixf or glUniformMatrix4fv functions.

If the underlying buffer has a crop associated with it, the transformation will also include a slight scale to cut off a 1-texel border around the edge of the crop. This ensures that when the texture is bilinear sampled that no texels outside of the buffer's valid region are accessed by the GPU, avoiding any sampling artifacts when scaling.

isReleased

open fun isReleased(): Boolean

Returns true if the SurfaceTexture was released.

release

open fun release(): Unit

release() frees all the buffers and puts the SurfaceTexture into the 'abandoned' state. Once put in this state the SurfaceTexture can never leave it. When in the 'abandoned' state, all methods of the IGraphicBufferProducer interface will fail with the NO_INIT error.

Note that while calling this method causes all the buffers to be freed from the perspective of the SurfaceTexture, if there are additional references on the buffers (e.g. if a buffer is referenced by a client or by OpenGL ES as a texture) then those buffer will remain allocated.

Always call this method when you are done with SurfaceTexture. Failing to do so may delay resource deallocation for a significant amount of time.

releaseTexImage

open fun releaseTexImage(): Unit

Releases the texture content. This is needed in single buffered mode to allow the image content producer to take ownership of the image buffer.

For more information see SurfaceTexture(int,boolean).

setDefaultBufferSize

open fun setDefaultBufferSize(
    width: Int, 
    height: Int
): Unit

Set the default size of the image buffers. The image producer may override the buffer size, in which case the producer-set buffer size will be used, not the default size set by this method. Both video and camera based image producers do override the size. This method may be used to set the image size when producing images with android.graphics.Canvas (via android.view.Surface#lockCanvas), or OpenGL ES (via an EGLSurface).

The new default buffer size will take effect the next time the image producer requests a buffer to fill. For android.graphics.Canvas this will be the next time android.view.Surface#lockCanvas is called. For OpenGL ES, the EGLSurface should be destroyed (via eglDestroySurface), made not-current (via eglMakeCurrent), and then recreated (via eglCreateWindowSurface) to ensure that the new default size has taken effect.

The width and height parameters must be no greater than the minimum of GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see javax.microedition.khronos.opengles.GL10#glGetIntegerv). An error due to invalid dimensions might not be reported until updateTexImage() is called.

setOnFrameAvailableListener

open fun setOnFrameAvailableListener(listener: SurfaceTexture.OnFrameAvailableListener?): Unit

Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.

The callback may be called on an arbitrary thread, so it is not safe to call updateTexImage without first binding the OpenGL ES context to the thread invoking the callback.

setOnFrameAvailableListener

open fun setOnFrameAvailableListener(
    listener: SurfaceTexture.OnFrameAvailableListener?, 
    handler: Handler?
): Unit

Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.

If a handler is specified, the callback will be invoked on that handler's thread. If no handler is specified, then the callback may be called on an arbitrary thread, so it is not safe to call updateTexImage without first binding the OpenGL ES context to the thread invoking the callback.

updateTexImage

open fun updateTexImage(): Unit

Update the texture image to the most recent frame from the image stream. This may only be called while the OpenGL ES context that owns the texture is current on the calling thread. It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.

finalize

protected open fun finalize(): Unit