# Print output for @column tags ?>
Developers

- Design
- Develop
- Distribute

Developer Console

## Most visited

## Recently visited

## Results for

Summary: Nested Classes | Ctors | Methods | Protected Methods | Inherited Methods

# SurfaceTexture

`public class SurfaceTexture`
`extends Object` ``

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

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

The image stream may come from either camera preview or video decode. A `Surface` created from a SurfaceTexture can be used as an output destination for the `android.hardware.camera2`, `MediaCodec`, `MediaPlayer`, and `Allocation` APIs. When `updateTexImage()` is called, the contents of the texture object specified when the SurfaceTexture was created are updated to contain the most recent image from the image stream. This may cause some frames of the stream to be skipped.

A SurfaceTexture may also be used in place of a SurfaceHolder when specifying the output destination of the older `Camera` API. 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 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 GL_OES_EGL_image_external OpenGL ES extension. This limits how the texture may be used. Each time the texture is bound it must be bound to the GL_TEXTURE_EXTERNAL_OES target rather than the GL_TEXTURE_2D target. Additionally, any OpenGL ES 2.0 shader that samples from the texture must declare its use of this extension using, for example, an "#extension GL_OES_EGL_image_external : require" directive. Such shaders must also access the texture using the samplerExternalOES GLSL sampler type.

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` This class is deprecated. No longer thrown. `Surface.OutOfResourcesException` is used instead.

### Public constructors
`SurfaceTexture(int texName)` Construct a new SurfaceTexture to stream images to a given OpenGL texture.
`SurfaceTexture(int texName, boolean singleBufferMode)` Construct a new SurfaceTexture to stream images to a given OpenGL texture.
`SurfaceTexture(boolean singleBufferMode)` Construct a new SurfaceTexture to stream images to a given OpenGL texture.

### Public methods
`void` | `attachToGLContext(int texName)` Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread.
`void` | `detachFromGLContext()` Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object.
`long` | `getTimestamp()` Retrieve the timestamp associated with the texture image set by the most recent call to `updateTexImage()`.
`void` | `getTransformMatrix(float[] mtx)` Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to `updateTexImage()`.
`boolean` | `isReleased()` Returns `true` if the SurfaceTexture was released.
`void` | `release()` `release()` frees all the buffers and puts the SurfaceTexture into the 'abandoned' state.
`void` | `releaseTexImage()` Releases the the texture content.
`void` | `setDefaultBufferSize(int width, int height)` Set the default size of the image buffers.
`void` | `setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener listener)` Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.
`void` | `setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener listener, Handler handler)` 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 by the garbage collector on an object when garbage collection determines that there are no more references to the object.

### Inherited methods
From class `java.lang.Object`
`Object` | `clone()` Creates and returns a copy of this object.
`boolean` | `equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void` | `finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>` | `getClass()` Returns the runtime class of this `Object`.
`int` | `hashCode()` Returns a hash code value for the object.
`final void` | `notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void` | `notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String` | `toString()` Returns a string representation of the object.
`final void` | `wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void` | `wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void` | `wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

## Public constructors

### SurfaceTexture

    public SurfaceTexture (int texName)

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

Parameters
`texName` | `int`: the OpenGL texture object name (e.g. generated via glGenTextures)

Throws
`Surface.OutOfResourcesException` | If the SurfaceTexture cannot be created.

### SurfaceTexture

    public SurfaceTexture (int texName,
                    boolean singleBufferMode)

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.

Parameters
`texName` | `int`: the OpenGL texture object name (e.g. generated via glGenTextures)
`singleBufferMode` | `boolean`: whether the SurfaceTexture will be in single buffered mode.

Throws
`Surface.OutOfResourcesException` | If the SurfaceTexture cannot be created.

### SurfaceTexture

    public SurfaceTexture (boolean singleBufferMode)

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(int)` before calling `releaseTexImage()` and producing image content using OpenGL ES.

Parameters
`singleBufferMode` | `boolean`: whether the SurfaceTexture will be in single buffered mode.

Throws
`Surface.OutOfResourcesException` | If the SurfaceTexture cannot be created.

## Public methods

### attachToGLContext

    public void attachToGLContext (int texName)

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.

Parameters
`texName` | `int`: The name of the OpenGL ES texture that will be created. This texture name must be unusued in the OpenGL ES context that is current on the calling thread.

### detachFromGLContext

    public void detachFromGLContext ()

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 `IllegalStateException` until a successful call to `attachToGLContext(int)` 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.

### getTimestamp

    public long getTimestamp ()

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.

Returns
`long` |

### getTransformMatrix

    public void getTransformMatrix (float[] mtx)

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.

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

### isReleased

    public boolean isReleased ()

Returns `true` if the SurfaceTexture was released.

Returns
`boolean` |

See also:

- `release()`

### release

    public void release ()

`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 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.

See also:

- `isReleased()`

### releaseTexImage

    public void releaseTexImage ()

Releases the 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

    public void setDefaultBufferSize (int width,
                    int height)

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 `Canvas` (via `Surface.lockCanvas(Rect)`), 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 `Canvas` this will be the next time `Surface.lockCanvas(Rect)` 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 `glGetIntegerv`). An error due to invalid dimensions might not be reported until updateTexImage() is called.

Parameters
`width` | `int`
`height` | `int`

### setOnFrameAvailableListener

    public void setOnFrameAvailableListener (SurfaceTexture.OnFrameAvailableListener listener)

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.

Parameters
`listener` | `SurfaceTexture.OnFrameAvailableListener`: The listener to use, or null to remove the listener. This value may be `null`.

### setOnFrameAvailableListener

    public void setOnFrameAvailableListener (SurfaceTexture.OnFrameAvailableListener listener,
                    Handler handler)

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.

Parameters
`listener` | `SurfaceTexture.OnFrameAvailableListener`: The listener to use, or null to remove the listener. This value may be `null`.
`handler` | `Handler`: The handler on which the listener should be invoked, or null to use an arbitrary thread. This value may be `null`.

### updateTexImage

    public void updateTexImage ()

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.

## Protected methods

### finalize

    protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the `finalize` method to dispose of system resources or to perform other cleanup.

The general contract of `finalize` is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The `finalize` method may take any action, including making this object available again to other threads; the usual purpose of `finalize`, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The `finalize` method of class `Object` performs no special action; it simply returns normally. Subclasses of `Object` may override this definition.

The Java programming language does not guarantee which thread will invoke the `finalize` method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the `finalize` method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The `finalize` method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the `finalize` method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
`Throwable` |

Full name *
Email address *
Company / developer name
One of your Play Store app URLs *
Which best describes your business:*
Apps
Games
Apps & Games
*
*