SurfaceTexture

SurfaceTexture

从图像流中捕获帧作为OpenGL ES纹理。

图像流可以来自相机预览或视频解码。从SurfaceTexture创建的纹理对象可用作API的输出目标，包括Camera、MediaCodec、MediaPlayer和Allocation。调用updateTexImage()时，指定SurfaceTexture创建时的纹理对象的内容将更新为图像流中最新的图像。这可能会导致一些帧被跳过。SurfaceTexture还可以用作旧API中指定输出目标的SurfaceHolder的替代品。这样做会将图像流中的所有帧发送到SurfaceTexture对象，而不是设备的显示器。

通常的模式是使用SurfaceTexture将帧呈现到TextureView上；但是，使用纹理对象并不需要TextureView。纹理对象可以作为OpenGL ES着色器的一部分使用。

在从纹理中取样时，应首先使用通过getTransformMatrix(float[])查询的矩阵转换纹理坐标。变换矩阵可能每次调用updateTexImage()时都会发生变化，因此每次更新纹理图像时都应重新查询。该矩阵将传统的2D OpenGL ES纹理坐标列向量（形式为（s，t，0，1），其中s和t在包括区间[0,1]）转换为流式纹理中的适当采样位置。该变换补偿了图像流源的任何属性，使其与传统的OpenGL ES纹理不同。例如，可以通过使用查询的矩阵转换列向量（0，0，0，1）从图像的左下角采样，而可以通过使用转换（1，1，0，1）从图像的右上角采样。

纹理对象使用GL_TEXTURE_EXTERNAL_OES纹理目标，该目标由GL_OES_EGL_image_external OpenGL ES扩展定义。这限制了纹理的使用方式。每次绑定纹理时，它必须绑定到GL_TEXTURE_EXTERNAL_OES目标而不是GL_TEXTURE_2D目标。此外，任何OpenGL ES 2.0着色器从纹理中取样时必须使用该扩展声明其使用，例如使用“#extension GL_OES_EGL_image_external : require”指令。这样的着色器还必须使用samplerExternalOES GLSL采样器类型访问纹理。

SurfaceTexture对象可以在任何线程上创建。只有包含纹理对象的OpenGL ES上下文的线程才能调用updateTexImage()。帧可用回调在任意线程上调用，因此除非特别注意，否则不应直接从回调中调用updateTexImage()。

内部类

interface    SurfaceTexture.OnFrameAvailableListener
用于通知新的流帧可用的回调接口。

class    SurfaceTexture.OutOfResourcesException
此类已在API级别19中被弃用。不再抛出。现在使用Surface.OutOfResourcesException。

公共构造函数

SurfaceTexture(int texName)
构造一个新的SurfaceTexture以将图像流传输到给定的OpenGL纹理。

SurfaceTexture(int texName, boolean singleBufferMode)
构造一个新的SurfaceTexture以将图像流传输到给定的OpenGL纹理，并指定是否使用单缓冲模式。

SurfaceTexture(boolean singleBufferMode)
构造一个新的SurfaceTexture以将图像流传输到给定的OpenGL纹理，并指定是否使用单缓冲模式。如果未指定纹理名称，则会自动创建一个新的纹理。

公共方法

void attachToGLContext(int texName)
将 SurfaceTexture 附加到当前线程的 OpenGL ES 上下文中，使用指定的纹理名称。

void detachFromGLContext()
将 SurfaceTexture 从拥有 OpenGL ES 纹理对象的 OpenGL ES 上下文中分离。

int getDataSpace()
检索与纹理图像关联的数据空间。

long getTimestamp()
检索与纹理图像关联的时间戳，该时间戳由最近一次调用 updateTexImage() 方法设置。

void getTransformMatrix(float[] mtx)
检索与纹理图像关联的 4x4 纹理坐标变换矩阵，该矩阵由最近一次调用 updateTexImage() 方法设置。

boolean isReleased()
返回 SurfaceTexture 是否已释放。

void release()
释放所有缓冲区并将 SurfaceTexture 置于“废弃”状态。

void releaseTexImage()
释放纹理内容。

void setDefaultBufferSize(int width, int height)
设置图像缓冲区的默认大小。

void setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener listener, Handler handler)
注册回调函数，在新的图像帧可用于 SurfaceTexture 时调用。

void setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener listener)
注册回调函数，在新的图像帧可用于 SurfaceTexture 时调用。

void updateTexImage()
将纹理图像更新为图像流中最近的帧。