Android Guides | Samples

Android.Graphics.SurfaceTexture Class

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

See Also: SurfaceTexture

Syntax

[Android.Runtime.Register("android/graphics/SurfaceTexture", DoNotGenerateAcw=true)]
public class SurfaceTexture : Object

Remarks

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 SurfaceTexture.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 SurfaceTexture.GetTransformMatrix(Single[]). The transform matrix may change each time SurfaceTexture.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 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. SurfaceTexture.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 SurfaceTexture.UpdateTexImage should not be called directly from the callback.

[Android Documentation]

Requirements

Namespace: Android.Graphics
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 11

The members of Android.Graphics.SurfaceTexture are listed below.

See Also: Object

Public Constructors

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

Protected Constructors

A constructor used when creating managed representations of JNI objects; called by the runtime.

Public Properties

[read-only]
TimestampInt64. Retrieve the timestamp associated with the texture image set by the most recent call to updateTexImage.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

AttachToGLContext(Int32)
Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread.
DetachFromGLContext()
Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object.
GetTransformMatrix(Single[])
Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to updateTexImage.
Release()
release() frees all the buffers and puts the SurfaceTexture into the 'abandoned' state.
ReleaseTexImage()
Releases the the texture content.
SetDefaultBufferSize(Int32, Int32)
Set the default size of the image buffers.
SetOnFrameAvailableListener(SurfaceTexture+IOnFrameAvailableListener)
Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.
SetOnFrameAvailableListener(SurfaceTexture+IOnFrameAvailableListener, Handler)
Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.
UpdateTexImage()
Update the texture image to the most recent frame from the image stream.

Public Events