原生窗口

ANativeWindow 表示图像队列的生产者端。

摘要

ANativeWindow 的 Parcelable 支持。

它是 Java 中 android.view.Surface 对象的 C 语言对应物，可以双向转换。根据消费者不同，提交到 ANativeWindow 的图像可以显示在屏幕上，也可以发送给其他消费者，例如视频编码器。

可与 libbinder_ndk 配合使用

枚举
`ANativeWindowTransform{ ANATIVEWINDOW_TRANSFORM_IDENTITY = 0x00, ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL = 0x01, ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL = 0x02, ANATIVEWINDOW_TRANSFORM_ROTATE_90 = 0x04, ANATIVEWINDOW_TRANSFORM_ROTATE_180 = ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL \| ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL, ANATIVEWINDOW_TRANSFORM_ROTATE_270 = ANATIVEWINDOW_TRANSFORM_ROTATE_180 \| ANATIVEWINDOW_TRANSFORM_ROTATE_90 }`	enum 应用于缓冲区在窗口中显示时使用的变换。
`ANativeWindow_ChangeFrameRateStrategy{ ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS = 0, ANATIVEWINDOW_CHANGE_FRAME_RATE_ALWAYS = 1 }`	enum ANativeWindow_setFrameRate 的帧速率更改策略值。
`ANativeWindow_FrameRateCompatibility{ ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT = 0, ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE = 1 }`	enum ANativeWindow_setFrameRate 的兼容性值。
`ANativeWindow_LegacyFormat{ WINDOW_FORMAT_RGBA_8888 = AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM, WINDOW_FORMAT_RGBX_8888 = AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM, WINDOW_FORMAT_RGB_565 = AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM }`	enum 旧版窗口像素格式名称，保留以实现向后兼容性。

类型定义
`ANativeWindow`	typedef `struct ANativeWindow` 提供对原生窗口访问权限的不透明类型。
`ANativeWindow_Buffer`	typedef `struct ANativeWindow_Buffer` 表示窗口缓冲区的结构体。

函数
`ANativeWindow_acquire(ANativeWindow *window)`	`void` 获取给定 ANativeWindow 对象的引用。
`ANativeWindow_clearFrameRate(ANativeWindow *window)`	`int32_t` 清除为此窗口设置的帧速率。
`ANativeWindow_getBuffersDataSpace(ANativeWindow *window)`	`int32_t` 获取窗口中缓冲区的数据空间。
`ANativeWindow_getBuffersDefaultDataSpace(ANativeWindow *window)`	`int32_t` 获取由消费者设置的窗口中缓冲区的默认数据空间。
`ANativeWindow_getFormat(ANativeWindow *window)`	`int32_t` 返回窗口表面的当前像素格式 (AHARDWAREBUFFER_FORMAT_*)。
`ANativeWindow_getHeight(ANativeWindow *window)`	`int32_t` 返回窗口表面的当前像素高度。
`ANativeWindow_getWidth(ANativeWindow *window)`	`int32_t` 返回窗口表面的当前像素宽度。
`ANativeWindow_lock(ANativeWindow window, ANativeWindow_Buffer outBuffer, ARect *inOutDirtyBounds)`	`int32_t` 锁定窗口的下一个绘制表面以供写入。
`ANativeWindow_readFromParcel(const AParcel _Nonnull parcel, ANativeWindow _Nullable *_Nonnull outWindow)`	`binder_status_t` 从 AParcel 中读取 ANativeWindow。
`ANativeWindow_release(ANativeWindow *window)`	`void` 移除之前使用 ANativeWindow_acquire() 获取的引用。
`ANativeWindow_setBuffersDataSpace(ANativeWindow *window, int32_t dataSpace)`	`int32_t` 此调用后入队的所有缓冲区都将与指定的 dataSpace 参数相关联。
`ANativeWindow_setBuffersGeometry(ANativeWindow *window, int32_t width, int32_t height, int32_t format)`	`int32_t` 更改窗口缓冲区的格式和大小。
`ANativeWindow_setBuffersTransform(ANativeWindow *window, int32_t transform)`	`int32_t` 设置将应用于将来发布到窗口的缓冲区的变换。
`ANativeWindow_setFrameRate(ANativeWindow *window, float frameRate, int8_t compatibility)`	`int32_t` 与 ANativeWindow_setFrameRateWithChangeStrategy(window, frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS) 相同。
`ANativeWindow_setFrameRateWithChangeStrategy(ANativeWindow *window, float frameRate, int8_t compatibility, int8_t changeFrameRateStrategy)`	`int32_t` 设置此窗口的预期帧速率。
`ANativeWindow_tryAllocateBuffers(ANativeWindow *window)`	`void` 向窗口提供提示，表明应提前预分配缓冲区。
`ANativeWindow_unlockAndPost(ANativeWindow *window)`	`int32_t` 解锁先前锁定的窗口绘制表面，将新缓冲区发布到显示器。
`ANativeWindow_writeToParcel(ANativeWindow _Nonnull window, AParcel _Nonnull parcel)`	`binder_status_t` 将 ANativeWindow 写入 AParcel。

结构体
ANativeWindow_Buffer	表示窗口缓冲区的结构体。

枚举

ANativeWindowTransform

在 android/native_window.h 中声明

 ANativeWindowTransform

应用于缓冲区在窗口中显示时使用的变换。

支持的变换包括水平镜像、垂直镜像和顺时针 90 度旋转的任意组合，按此顺序进行。180 度和 270 度旋转由这些基本变换组成。

属性
`ANATIVEWINDOW_TRANSFORM_IDENTITY`
`ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL`
`ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL`
`ANATIVEWINDOW_TRANSFORM_ROTATE_180`
`ANATIVEWINDOW_TRANSFORM_ROTATE_270`
`ANATIVEWINDOW_TRANSFORM_ROTATE_90`

ANativeWindow_ChangeFrameRateStrategy

在 android/native_window.h 中声明

 ANativeWindow_ChangeFrameRateStrategy

ANativeWindow_setFrameRate 的帧速率更改策略值。

属性

属性
`ANATIVEWINDOW_CHANGE_FRAME_RATE_ALWAYS`	即使转换将是非无缝的，即对用户造成视觉中断，也更改帧速率。
`ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS`	仅当转换将是无缝的时才更改帧速率。

ANATIVEWINDOW_CHANGE_FRAME_RATE_ALWAYS

即使转换将是非无缝的，即

对用户造成视觉中断，也更改帧速率。

ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS

仅当转换将是无缝的时才更改帧速率。

ANativeWindow_FrameRateCompatibility

在 android/native_window.h 中声明

 ANativeWindow_FrameRateCompatibility

ANativeWindow_setFrameRate 的兼容性值。

属性

属性
`ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT`	此窗口的帧速率没有固有限制。当系统选择的应用请求的帧速率以外的帧速率时，应用将能够以系统帧速率运行而无需进行拉伸。此值应用于显示游戏内容、UI 以及任何非视频内容时使用。
`ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE`	此窗口用于显示具有固有固定帧速率的内容，例如具有特定帧速率的视频。当系统选择的应用请求的帧速率以外的帧速率时，应用将需要进行拉伸或使用其他技术来适应系统的帧速率。用户体验可能会比系统选择应用请求的帧速率时更差（例如，帧卡顿更多）。此值应用于视频内容。

ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT

此窗口的帧速率没有固有限制。

当系统选择的应用请求的帧速率以外的帧速率时，应用将能够以系统帧速率运行而无需进行拉伸。此值应用于显示游戏内容、UI 以及任何非视频内容时使用。

ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE

此窗口用于显示具有固有固定帧速率的内容，例如具有特定帧速率的视频。

当系统选择的应用请求的帧速率以外的帧速率时，应用将需要进行拉伸或使用其他技术来适应系统的帧速率。用户体验可能会比系统选择应用请求的帧速率时更差（例如，帧卡顿更多）。此值应用于视频内容。

ANativeWindow_LegacyFormat

在 android/native_window.h 中声明

 ANativeWindow_LegacyFormat

旧版窗口像素格式名称，保留以实现向后兼容性。

新的代码和 API 应使用 AHARDWAREBUFFER_FORMAT_*。

属性
`WINDOW_FORMAT_RGBA_8888`	红色：8 位，绿色：8 位，蓝色：8 位，Alpha：8 位。
`WINDOW_FORMAT_RGBX_8888`	红色：8 位，绿色：8 位，蓝色：8 位，未使用：8 位。
`WINDOW_FORMAT_RGB_565`	红色：5 位，绿色：6 位，蓝色：5 位。

类型定义

ANativeWindow

在 android/native_window.h 中声明

struct ANativeWindow ANativeWindow

提供对原生窗口访问权限的不透明类型。

可以使用 ANativeWindow_fromSurface() 获取指针。

ANativeWindow_Buffer

在 android/native_window.h 中声明

struct ANativeWindow_Buffer ANativeWindow_Buffer

表示窗口缓冲区的结构体。

可以使用 ANativeWindow_lock() 获取指针。

函数

ANativeWindow_acquire

在 android/native_window.h 中声明

void ANativeWindow_acquire(
  ANativeWindow *window
)

获取给定 ANativeWindow 对象的引用。

这会阻止对象被删除，直到引用被移除。

ANativeWindow_clearFrameRate

在 android/native_window.h 中声明

int32_t ANativeWindow_clearFrameRate(
  ANativeWindow *window
)

清除为此窗口设置的帧速率。

这等同于调用 ANativeWindow_setFrameRateWithChangeStrategy(window, 0, compatibility, changeFrameRateStrategy)。

使用此 API 不会引入帧速率限制，也不会影响应用程序帧生产流水线的其他方面。但是，由于系统可能会更改显示刷新率，因此对此函数的调用可能会导致 Choreographer 回调时间发生变化，以及系统将缓冲区释放回应用程序的时间间隔发生变化。

请注意，这仅对显示在屏幕上的窗口有效。如果此 ANativeWindow 由系统合成器以外的其他东西（例如媒体编解码器）使用，则此调用无效。

您可以使用 AChoreographer_registerRefreshRateCallback 注册刷新率更改。

请参阅 ANativeWindow_setFrameRateWithChangeStrategy()。

自 API 级别 31 起可用。

详细信息

参数

window

指向 ANativeWindow 对象的指针。

返回值

成功返回 0，如果窗口值无效则返回 -EINVAL。

ANativeWindow_getBuffersDataSpace

在 android/native_window.h 中声明

int32_t ANativeWindow_getBuffersDataSpace(
  ANativeWindow *window
)

获取窗口中缓冲区的数据空间。

自 API 级别 28 起可用。

详细信息
返回值	窗口中缓冲区的数据空间，如果数据空间未知则返回 ADATASPACE_UNKNOWN，如果窗口无效则返回 -EINVAL。

ANativeWindow_getBuffersDefaultDataSpace

在 android/native_window.h 中声明

int32_t ANativeWindow_getBuffersDefaultDataSpace(
  ANativeWindow *window
)

获取由消费者设置的窗口中缓冲区的默认数据空间。

自 API 级别 34 起可用。

详细信息
返回值	窗口中缓冲区的数据空间，如果数据空间未知则返回 ADATASPACE_UNKNOWN，如果窗口无效则返回 -EINVAL。

ANativeWindow_getFormat

在 android/native_window.h 中声明

int32_t ANativeWindow_getFormat(
  ANativeWindow *window
)

返回窗口表面的当前像素格式 (AHARDWAREBUFFER_FORMAT_*)。

详细信息
返回值	错误时返回负值。

ANativeWindow_getHeight

在 android/native_window.h 中声明

int32_t ANativeWindow_getHeight(
  ANativeWindow *window
)

返回窗口表面的当前像素高度。

详细信息
返回值	错误时返回负值。

ANativeWindow_getWidth

在 android/native_window.h 中声明

int32_t ANativeWindow_getWidth(
  ANativeWindow *window
)

返回窗口表面的当前像素宽度。

详细信息
返回值	错误时返回负值。

ANativeWindow_lock

在 android/native_window.h 中声明

int32_t ANativeWindow_lock(
  ANativeWindow *window,
  ANativeWindow_Buffer *outBuffer,
  ARect *inOutDirtyBounds
)

锁定窗口的下一个绘制表面以供写入。

inOutDirtyBounds 用作输入/输出参数，进入函数时，它包含脏区域，即调用方打算重新绘制的区域。当函数返回时，inOutDirtyBounds 会更新为调用方需要重新绘制的实际区域，此区域通常由 ANativeWindow_lock 扩展。

详细信息
返回值	成功返回 0，错误时返回负值。

ANativeWindow_readFromParcel

在 android/native_window_aidl.h 中声明

binder_status_t ANativeWindow_readFromParcel(
  const AParcel *_Nonnull parcel,
  ANativeWindow *_Nullable *_Nonnull outWindow
)

从 AParcel 中读取 ANativeWindow。

输出缓冲区将获得初始引用，并且需要使用 ANativeWindow_release 释放。

自 API 级别 34 起可用。

详细信息
返回值	成功返回 STATUS_OK，如果 parcel 或 outBuffer 为 null 或反序列化出现问题（例如，损坏的 parcel）则返回 STATUS_BAD_VALUE，如果 parcel 当前数据位置不是 ANativeWindow 类型则返回 STATUS_BAD_TYPE，如果分配失败则返回 STATUS_NO_MEMORY。

ANativeWindow_release

在 android/native_window.h 中声明

void ANativeWindow_release(
  ANativeWindow *window
)

移除之前使用 ANativeWindow_acquire() 获取的引用。

ANativeWindow_setBuffersDataSpace

在 android/native_window.h 中声明

int32_t ANativeWindow_setBuffersDataSpace(
  ANativeWindow *window,
  int32_t dataSpace
)

此调用后入队的所有缓冲区都将与指定的 dataSpace 参数相关联。

dataSpace 指定有关缓冲区的附加信息。例如，它可以用于传达缓冲区中图像数据的颜色空间，或者可以用于指示缓冲区包含深度测量数据而不是彩色图像。默认的 dataSpace 为 0，即 ADATASPACE_UNKNOWN，除非被生产者覆盖。

自 API 级别 28 起可用。

详细信息

参数

`window`	指向 ANativeWindow 对象的指针。
`dataSpace`	此调用后入队的所有缓冲区的数据空间。

返回值

成功返回 0，如果 window 无效或 dataspace 不受支持则返回 -EINVAL。

ANativeWindow_setBuffersGeometry

在 android/native_window.h 中声明

int32_t ANativeWindow_setBuffersGeometry(
  ANativeWindow *window,
  int32_t width,
  int32_t height,
  int32_t format
)

更改窗口缓冲区的格式和大小。

宽度和高度控制缓冲区中的像素数量，而不是屏幕上窗口的尺寸。如果这些与窗口的物理尺寸不同，则其缓冲区在合成到屏幕时将缩放以匹配该尺寸。宽度和高度必须都是零或都不是零。

对于所有这些参数，如果提供 0，则窗口的基本值将重新生效。

详细信息

参数

`window`	指向 ANativeWindow 对象的指针。
`width`	缓冲区宽度（像素）。
`height`	缓冲区高度（像素）。
`format`	AHardwareBuffer_Format 常量之一。

返回值

成功返回 0，错误时返回负值。

ANativeWindow_setBuffersTransform

在 android/native_window.h 中声明

int32_t ANativeWindow_setBuffersTransform(
  ANativeWindow *window,
  int32_t transform
)

设置将应用于将来发布到窗口的缓冲区的变换。

自 API 级别 26 起可用。

详细信息

参数

`window`	指向 ANativeWindow 对象的指针。
`transform`	ANativeWindowTransform 标志的组合

返回值

成功返回 0，如果 transform 无效则返回 -EINVAL

ANativeWindow_setFrameRate

在 android/native_window.h 中声明

int32_t ANativeWindow_setFrameRate(
  ANativeWindow *window,
  float frameRate,
  int8_t compatibility
)

与 ANativeWindow_setFrameRateWithChangeStrategy(window, frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS) 相同。

请参阅 ANativeWindow_setFrameRateWithChangeStrategy()。

自 API 级别 30 起可用。

ANativeWindow_setFrameRateWithChangeStrategy

在 android/native_window.h 中声明

int32_t ANativeWindow_setFrameRateWithChangeStrategy(
  ANativeWindow *window,
  float frameRate,
  int8_t compatibility,
  int8_t changeFrameRateStrategy
)

设置此窗口的预期帧速率。

在能够以不同刷新率运行显示的设备上，系统可能会选择显示刷新率以更好地匹配此窗口的帧速率。使用此 API 不会引入帧速率限制，也不会影响应用程序帧生产流水线的其他方面。但是，由于系统可能会更改显示刷新率，因此对此函数的调用可能会导致 Choreographer 回调时间发生变化，以及系统将缓冲区释放回应用程序的时间间隔发生变化。

请注意，这仅对显示在屏幕上的窗口有效。如果此 ANativeWindow 由系统合成器以外的其他东西（例如媒体编解码器）使用，则此调用无效。

您可以使用 AChoreographer_registerRefreshRateCallback 注册刷新率更改。

请参阅 ANativeWindow_clearFrameRate()。

自 API 级别 31 起可用。

详细信息

参数

`window`	指向 ANativeWindow 对象的指针。
`frameRate`	此窗口的预期帧速率，单位为每秒帧数。0 是一个特殊值，表示应用将接受系统对显示帧速率的选择，如果未调用此函数，则这是默认行为。frameRate 参数不需要是此设备显示的有效刷新率 - 例如，向只能以 60fps 运行显示的设备传递 30fps 是可以的。
`compatibility`	此窗口的帧速率兼容性。兼容性值可能会影响系统对显示刷新率的选择。有关更多信息，请参阅 ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_* 值。当 frameRate 为 0 时，此参数将被忽略。
`changeFrameRateStrategy`	此窗口导致的显示刷新率转换是否应是无缝的。无缝转换是没有任何视觉中断的转换，例如一两秒的黑屏。请参阅 ANATIVEWINDOW_CHANGE_FRAME_RATE_* 值。当 frameRate 为 0 时，此参数将被忽略。

返回值

成功返回 0，如果 window、frame rate 或 compatibility 值无效则返回 -EINVAL。

ANativeWindow_tryAllocateBuffers

在 android/native_window.h 中声明

void ANativeWindow_tryAllocateBuffers(
  ANativeWindow *window
)

向窗口提供提示，表明应提前预分配缓冲区。

请注意，窗口实现不保证预分配任何缓冲区，例如如果某个实现禁止分配新缓冲区，或者如果系统中没有足够的内存来预分配附加缓冲区

自 API 级别 30 起可用。

ANativeWindow_unlockAndPost

在 android/native_window.h 中声明

int32_t ANativeWindow_unlockAndPost(
  ANativeWindow *window
)

解锁先前锁定的窗口绘制表面，将新缓冲区发布到显示器。

详细信息
返回值	成功返回 0，错误时返回负值。

ANativeWindow_writeToParcel

在 android/native_window_aidl.h 中声明

binder_status_t ANativeWindow_writeToParcel(
  ANativeWindow *_Nonnull window,
  AParcel *_Nonnull parcel
)

将 ANativeWindow 写入 AParcel。

自 API 级别 34 起可用。

详细信息
返回值	成功返回 STATUS_OK。如果 buffer 或 parcel 为 null，或者 ANativeWindow* 序列化失败（例如，内部损坏）则返回 STATUS_BAD_VALUE；如果 parcel 没有足够的空间存储 buffer 且无法分配更多空间，则返回 STATUS_NO_MEMORY；如果 parcel 不允许存储 FD，则返回 STATUS_FDS_NOT_ALLOWED。