public class

SurfaceTexture

extends Object
java.lang.Object
   ↳ android.graphics.SurfaceTexture

Class Overview

Captures frames from an image stream as an OpenGL ES texture.

The image stream may come from either camera preview. A SurfaceTexture may be used in place of a SurfaceHolder when specifying the output destination of a Camera object. Doing so will cause all the frames from the image stream to be sent to the SurfaceTexture object rather than to the device's display. When updateTexImage() is called, the contents of the texture object specified when the SurfaceTexture was created is updated to contain the most recent image from the image stream. This may cause some frames of the stream to be skipped.

When sampling from the texture one should first transform the texture coordinates using the matrix queried via getTransformMatrix(float[]). The transform matrix may change each time updateTexImage() is called, so it should be re-queried each time the texture image is updated. This matrix transforms traditional 2D OpenGL ES texture coordinate column vectors of the form (s, t, 0, 1) where s and t are on the inclusive interval [0, 1] to the proper sampling location in the streamed texture. This transform compensates for any properties of the image stream source that cause it to appear different from a traditional OpenGL ES texture. For example, sampling from the bottom left corner of the image can be accomplished by transforming the column vector (0, 0, 0, 1) using the queried matrix, while sampling from the top right corner of the image can be done by transforming (1, 1, 0, 1).

The texture object uses the GL_TEXTURE_EXTERNAL_OES texture target, which is defined by the OES_EGL_image_external OpenGL ES extension. This limits how the texture may be used.

SurfaceTexture objects may be created on any thread. updateTexImage() may only be called on the thread with the OpenGL ES context that contains the texture object. The frame-available callback is called on an arbitrary thread, so unless special care is taken updateTexImage() should not be called directly from the callback.

Summary

Nested Classes
interface SurfaceTexture.OnFrameAvailableListener Callback interface for being notified that a new stream frame is available. 
class SurfaceTexture.OutOfResourcesException Exception thrown when a surface couldn't be created or resized  
Public Constructors
SurfaceTexture(int texName)
Construct a new SurfaceTexture to stream images to a given OpenGL texture.
Public Methods
void getTransformMatrix(float[] mtx)
Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to updateTexImage.
void setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener l)
Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.
void updateTexImage()
Update the texture image to the most recent frame from the image stream.
Protected Methods
void finalize()
Called before the object's memory is reclaimed by the VM.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public SurfaceTexture (int texName)

Since: API Level 11

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

Parameters
texName the OpenGL texture object name (e.g. generated via glGenTextures)

Public Methods

public void getTransformMatrix (float[] mtx)

Since: API Level 11

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.

Parameters
mtx the array into which the 4x4 matrix will be stored. The array must have exactly 16 elements.

public void setOnFrameAvailableListener (SurfaceTexture.OnFrameAvailableListener l)

Since: API Level 11

Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture. Note that this 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.

public void updateTexImage ()

Since: API Level 11

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 bound to the thread. It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.

Protected Methods

protected void finalize ()

Since: API Level 11

Called before the object's memory is reclaimed by the VM. This can only happen once the garbage collector has detected that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.

Throws
Throwable