SurfaceTexture

摘要

类型定义
`ASurfaceTexture`	typedef `struct ASurfaceTexture` ASurfaceTexture 是一个不透明类型，用于通过原生代码管理 SurfaceTexture

函数
`ASurfaceTexture_acquireANativeWindow(ASurfaceTexture *st)`	`ANativeWindow *` 返回对 ANativeWindow 的引用（即
`ASurfaceTexture_attachToGLContext(ASurfaceTexture *st, uint32_t texName)`	`int` 将 SurfaceTexture 附加到调用线程上当前的 OpenGL ES 上下文。
`ASurfaceTexture_detachFromGLContext(ASurfaceTexture *st)`	`int` 从拥有 OpenGL ES 纹理对象的 OpenGL ES 上下文分离 SurfaceTexture。
`ASurfaceTexture_fromSurfaceTexture(JNIEnv *env, jobject surfacetexture)`	`ASurfaceTexture *` 从对应的 Java 对象获取原生 ASurfaceTexture 的引用。
`ASurfaceTexture_getTimestamp(ASurfaceTexture *st)`	`int64_t` 检索与最近一次调用 updateTexImage 设置的纹理图像关联的时间戳。
`ASurfaceTexture_getTransformMatrix(ASurfaceTexture *st, float mtx[16])`	`void` 检索与最近一次调用 updateTexImage 设置的纹理图像关联的 4x4 纹理坐标变换矩阵。
`ASurfaceTexture_release(ASurfaceTexture *st)`	`void` 释放使用 ASurfaceTexture_fromSurfaceTexture() 获取的原生 ASurfaceTexture 的引用。
`ASurfaceTexture_updateTexImage(ASurfaceTexture *st)`	`int` 将纹理图像更新为图像流中最新的帧。

类型定义

ASurfaceTexture

声明于 android/surface_texture.h

struct ASurfaceTexture ASurfaceTexture

ASurfaceTexture 是一个不透明类型，用于通过原生代码管理 SurfaceTexture

可以使用 ASurfaceTexture_fromSurfaceTexture() 从 android.graphics.SurfaceTexture 对象获取 ASurfaceTexture。

函数

ASurfaceTexture_acquireANativeWindow

声明于 android/surface_texture.h

ANativeWindow * ASurfaceTexture_acquireANativeWindow(
  ASurfaceTexture *st
)

返回对 ANativeWindow 的引用（即

此 SurfaceTexture 的生产者）。这相当于 Java 中的：Surface sur = new Surface(surfaceTexture);

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用

返回值

对 ANativeWindow 的引用。不再需要此引用时，必须使用 ANativeWindow_release() 释放。否则会导致资源泄露。如果 st 为 null 或不是 android.graphics.SurfaceTexture 的实例，则返回 nullptr。

ASurfaceTexture_attachToGLContext

声明于 android/surface_texture.h

int ASurfaceTexture_attachToGLContext(
  ASurfaceTexture *st,
  uint32_t texName
)

将 SurfaceTexture 附加到调用线程上当前的 OpenGL ES 上下文。

将创建一个新的 OpenGL ES 纹理对象，并使用上次调用 ASurfaceTexture_detachFromGLContext 时当前的 SurfaceTexture 图像帧填充该对象。此新纹理绑定到 GL_TEXTURE_EXTERNAL_OES 纹理目标。

此函数可用于从多个 OpenGL ES 上下文访问 SurfaceTexture 图像内容。但请注意，图像内容一次只能从一个 OpenGL ES 上下文访问。

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用
`texName`	将创建的 OpenGL ES 纹理的名称。在调用线程上当前的 OpenGL ES 上下文中，此纹理名称必须未使用。

返回值

成功时为 0，否则为负的 posix 错误代码（请参阅)

ASurfaceTexture_detachFromGLContext

声明于 android/surface_texture.h

int ASurfaceTexture_detachFromGLContext(
  ASurfaceTexture *st
)

从拥有 OpenGL ES 纹理对象的 OpenGL ES 上下文分离 SurfaceTexture。

必须在调用线程上当前的 OpenGL ES 上下文中进行此调用。调用此方法后，OpenGL ES 纹理对象将被删除。调用此方法后，在成功调用 ASurfaceTexture_attachToGLContext 之前，对 ASurfaceTexture_updateTexImage 的所有调用都将失败。

此函数可用于从多个 OpenGL ES 上下文访问 SurfaceTexture 图像内容。但请注意，图像内容一次只能从一个 OpenGL ES 上下文访问。

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用

返回值

成功时为 0，否则为负的 posix 错误代码（请参阅)

ASurfaceTexture_fromSurfaceTexture

声明于 android/surface_texture_jni.h

ASurfaceTexture * ASurfaceTexture_fromSurfaceTexture(
  JNIEnv *env,
  jobject surfacetexture
)

从对应的 Java 对象获取原生 ASurfaceTexture 的引用。

调用方必须在返回的 ASurfaceTexture 的生命周期内保留对 Java SurfaceTexture 的引用。否则，一旦 Java 对象被 finalization，ASurfaceTexture 可能会停止正常工作。但是，这不会导致程序终止。

自 API 级别 28 起可用。

详情

参数

`env`	JNI 环境
`surfacetexture`	Java SurfaceTexture 对象的实例

返回值

原生 ASurfaceTexture 引用；如果 Java 对象不是 SurfaceTexture，则为 nullptr。不再需要返回的引用时，必须使用 ASurfaceTexture_release() 释放。

ASurfaceTexture_getTimestamp

声明于 android/surface_texture.h

int64_t ASurfaceTexture_getTimestamp(
  ASurfaceTexture *st
)

检索与最近一次调用 updateTexImage 设置的纹理图像关联的时间戳。

此时间戳以纳秒为单位，通常是单调递增的。时间戳不应受时间调整影响，对于相机而言应严格单调递增，但对于 MediaPlayer 而言在设置位置时可能会重置。时间戳的具体含义和零点取决于向 SurfaceTexture 提供图像的源。除非图像源另有说明，否则通常无法在不同的 SurfaceTexture 实例或多次程序调用之间比较时间戳。它主要用于确定后续帧之间的时间偏移。

对于 EGL/Vulkan 生产者，此时间戳是使用 EGL_ANDROID_presentation_time 或 VK_GOOGLE_display_timing 扩展设置的预期显示时间。

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用

ASurfaceTexture_getTransformMatrix

声明于 android/surface_texture.h

void ASurfaceTexture_getTransformMatrix(
  ASurfaceTexture *st,
  float mtx[16]
)

检索与最近一次调用 updateTexImage 设置的纹理图像关联的 4x4 纹理坐标变换矩阵。

此变换矩阵将 s 和 t 在闭区间 [0, 1] 内的 (s, t, 0, 1) 形式的 2D 齐次纹理坐标映射到应从纹理中采样该位置的纹理坐标。在此变换范围之外采样纹理是未定义的行为。

矩阵按列主顺序存储，以便可以通过 glLoadMatrixf 或 glUniformMatrix4fv 函数直接传递给 OpenGL ES。

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用
`mtx`	存储 4x4 矩阵的数组。数组必须正好有 16 个元素。

ASurfaceTexture_release

声明于 android/surface_texture.h

void ASurfaceTexture_release(
  ASurfaceTexture *st
)

释放使用 ASurfaceTexture_fromSurfaceTexture() 获取的原生 ASurfaceTexture 的引用。

否则会导致内存和图形资源泄露。

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用

ASurfaceTexture_updateTexImage

声明于 android/surface_texture.h

int ASurfaceTexture_updateTexImage(
  ASurfaceTexture *st
)

将纹理图像更新为图像流中最新的帧。

只能在拥有该纹理的 OpenGL ES 上下文是调用线程上的当前上下文时调用此方法。它会隐式将其纹理绑定到 GL_TEXTURE_EXTERNAL_OES 纹理目标。

自 API 级别 28 起可用。

详情

参数

`st`	使用 ASurfaceTexture_fromSurfaceTexture() 获取的 ASurfaceTexture 引用

返回值

成功时为 0，否则为负的 posix 错误代码（请参阅)