graphic_graphic_surface/docs/knowledge/native-api-surface.md

Native API（Surface/NativeWindow/NativeBuffer）知识入口

适用范围

涉及 OH_NativeWindow_*、OH_NativeBuffer_* 公开 C API、NativeWindow 配置、NativeBuffer 操作、Surface 配置（format/usage/queue size/timeout）、BufferExtraData、SurfaceDelegate/TunnelHandle、错误码映射时，先读本文档。

快速代码索引

方向	主要文件
NativeWindow API 实现	surface/src/native_window.cpp
NativeBuffer API 实现	surface/src/native_buffer.cpp
公开 NativeWindow 头文件	interfaces/inner_api/surface/external_window.h
公开 NativeBuffer 头文件	interfaces/inner_api/surface/native_buffer.h
公共类型定义	interfaces/inner_api/surface/buffer_common.h、interfaces/inner_api/surface/surface_type.h
错误码	interfaces/inner_api/common/graphic_common_c.h、interfaces/inner_api/common/graphic_common.h
Surface 基类	interfaces/inner_api/surface/surface.h
单测	surface/test/unittest/native_window_test.cpp、surface/test/unittest/native_buffer_test.cpp
系统测试	surface/test/systemtest/

术语触发词

OH_NativeWindow、OH_NativeBuffer、OHNativeWindow、OHNativeWindowBuffer、NativeWindowHandleOpt、RequestBuffer、FlushBuffer、SetColorSpace、GetColorSpace、SetMetadataValue、GetMetadataValue、NativeBufferAlloc、NativeBufferReference、NativeBufferUnreference、BufferRequestConfig、BufferFlushConfig、OH_NativeBuffer_Config、OHSurfaceSource、OHScalingMode、usage、format

先判断的问题

• 改动涉及 NativeWindow 还是 NativeBuffer API？两者是否需要同步？
• 是否改变公开 API 行为（参数校验、返回值、错误码）？
• 是否影响 Surface 配置默认值（usage、format、timeout、colorGamut）？
• 是否涉及 deprecated API 的兼容性？
• 是否影响 NativeWindow 内部缓存（bufferCache_）管理？

关键边界

NativeWindow 默认配置：usage = BUFFER_USAGE_CPU_READ | BUFFER_USAGE_MEM_DMA、format = GRAPHIC_PIXEL_FMT_RGBA_8888、strideAlignment = 8、timeout = 3000ms、colorGamut = GRAPHIC_COLOR_GAMUT_SRGB、transform = GRAPHIC_ROTATE_NONE。HEBC 白名单应用去掉 BUFFER_USAGE_CPU_READ，只保留 BUFFER_USAGE_MEM_DMA。这些默认值是上层应用对 Surface 行为的基础假设，修改任何一个都可能影响渲染管线、内存分配策略和跨进程 buffer 传输效率。

OHNativeWindow 通过 NativeWindowMagic 字段做运行时类型检查：NATIVE_OBJECT_MAGIC_WINDOW 标识 OHNativeWindow、NATIVE_OBJECT_MAGIC_WINDOW_BUFFER 标识 OHNativeWindowBuffer、NATIVE_OBJECT_MAGIC_WINDOW_INVALID 在析构时设置。OH_NativeWindow_GetNativeObjectMagic 用于检查对象类型。这意味着使用已析构的 NativeWindow/NativeWindowBuffer 对象时，magic 字段已被置为 INVALID，调用方可以通过此机制检测 use-after-free，但如果跳过检查直接访问则会导致未定义行为。

OH_NativeWindow_NativeWindowHandleOpt 使用变参函数 + operationMap 分发，支持 25 个操作码（SET_USAGE=5、GET_USAGE=4、SET_FORMAT=3、GET_FORMAT=2、SET_BUFFER_GEOMETRY=0、GET_BUFFER_GEOMETRY=1、SET_STRIDE=6 deprecated since 16、GET_STRIDE=7 deprecated since 16、SET_TIMEOUT=10、GET_TIMEOUT=11、SET_COLOR_GAMUT=12、GET_COLOR_GAMUT=13、SET_TRANSFORM=14、GET_TRANSFORM=15、SET_UI_TIMESTAMP=16、GET_BUFFERQUEUE_SIZE=17、SET_SOURCE_TYPE=18、GET_SOURCE_TYPE=19、SET_APP_FRAMEWORK_TYPE=20、GET_APP_FRAMEWORK_TYPE=21、SET_HDR_WHITE_POINT_BRIGHTNESS=22、SET_SDR_WHITE_POINT_BRIGHTNESS=23、SET_DESIRED_PRESENT_TIMESTAMP=24）。变参函数参数类型不匹配会导致未定义行为，编译器无法检查变参类型，文档中每个操作码的参数类型必须严格遵守。

OH_NativeBuffer_Alloc 创建 SurfaceBufferImpl，设置 strideAlignment=8、colorGamut=SRGB、transform=NONE，调用 Alloc()，标记 DMA-BUF 为 external（通过 ioctl DMA_BUF_SET_NAME_A）。失败返回 nullptr。调用方必须检查返回值，否则后续对 nullptr 的解引用会直接崩溃。

OH_NativeBuffer_GetMetadataValue 使用 new uint8_t[] 分配输出缓冲区——调用方必须释放。OH_NativeBuffer_SetMetadataValue 按 metadataKey 分发：DYNAMIC/STATIC/METADATA_TYPE/ROI。ROI 上限 ROI_METADATA_CAPACITY(256) 字节。这是 C API 设计的典型所有权问题：输出缓冲区的生命周期管理完全依赖调用方，文档和头文件注释中必须明确说明所有权转移语义。

OH_NativeWindow_SetColorSpace 通过 SetUserData("ATTRKEY_COLORSPACE_INFO", ...) 存储为字符串；GetColorSpace 通过 GetUserData 反向查找。这与 NativeBuffer 的 HDI SetMetadata 方式不同，存在非确定性问题：多个枚举项可能编码为相同的字符串值，反向查找时 std::find_if 在 unordered_map 上可能返回不同枚举项，导致跨版本行为不一致（参见 docs/knowledge/metadata-colorspace-hdr.md）。

OH_NativeWindow_SetMetadataValue/GetMetadataValue 通过 Surface UserData 存储和读取元数据字符串，不经过 HDI。OH_NativeWindow_NativeWindowSetMetaData 和 NativeWindowSetMetaDataSet 是 deprecated since 10 的旧接口。两套接口的存储路径不同，混用可能导致数据读写不一致。

错误码映射：SURFACE_ERROR_OK(0)、SURFACE_ERROR_INVALID_PARAM(40001000)、SURFACE_ERROR_NOT_SUPPORT(50102000)、SURFACE_ERROR_UNKOWN(50002000)、SURFACE_ERROR_BUFFER_STATE_INVALID(41207000)、NATIVE_ERROR_OK(0)、NATIVE_ERROR_INVALID_ARGUMENTS(40001000)、NATIVE_ERROR_UNSUPPORTED(50102000)。GSErrorStr 函数将错误码转为可读字符串（如 "<500 api call failed>with low error <Not supported>"）。GSError 比较运算符只比较基码（除以 LOWERROR_MAX=1000），所以不同 low error 的同类错误被视为相等，这在错误码过滤或断言时可能掩盖细节差异。

OH_NativeWindow_WriteToParcel/ReadFromParcel 和 OH_NativeBuffer_WriteToParcel/ReadFromParcel 用于跨进程 IPC 序列化。NativeWindow parcel 传递 Surface 引用；NativeBuffer parcel 传递 BufferHandle。序列化格式变更会导致跨版本 IPC 不兼容，需要特别注意前向兼容性。

多个 API 版本共存：deprecated（since 8/9/10/12）和当前版本。OH_NativeWindow_CreateNativeWindow（deprecated since 12，用 OH_NativeWindow_CreateNativeWindowFromSurfaceId 替代）、OH_NativeWindow_NativeWindowSetScalingMode（deprecated since 10，用 OH_NativeWindow_NativeWindowSetScalingModeV2 替代）等。deprecated 版本仍需维护兼容性，不能在移除前改变行为或返回值。

NativeWindowLockBuffer/UnlockAndFlushBuffer 是 CPU 直接渲染模式：LockBuffer 请求 buffer、等 fence、映射；UnlockAndFlushBuffer 解除映射并刷回。同一时刻只允许一个 locked buffer（mLockedBuffer_），这意味着 CPU 渲染场景下无法双 buffer 流水线，是性能瓶颈所在。

appFrameworkType 上限 MAXIMUM_LENGTH_OF_APP_FRAMEWORK(64) 字节，影响 FrameReport 游戏帧率追踪。OHSurfaceSource 区分 DEFAULT/UI/GAME/CAMERA/VIDEO/LOWPOWERVIDEO。DAMAGES_MAX_SIZE = 1000 限制 Region 中的 damage rect 数量。META_DATA_MAX_SIZE = 3000 限制 HDR metadata 字节数。SURFACE_MAX_USER_DATA_COUNT = 1000 限制 UserData 键值对数量。这些上限值的变更会影响上层模块的数据完整性假设。

OH_NativeWindow_NativeWindowRequestBuffer 返回 buffer + fence fd（int*）。如果 buffer 已在 bufferCache_ 中命中，只更新 fence 不重新传输 buffer 数据。OH_NativeWindow_GetSurfaceId/OH_NativeWindow_CreateNativeWindowFromSurfaceId 通过 SurfaceId 跨进程传递 Surface 引用，避免直接暴露 sptr<Surface>。OH_NativeWindow_NativeWindowAttachBuffer/DetachBuffer 用于外部 buffer 的挂载/卸载。CreateNativeWindowFromSurface 初始化时会注册到 SurfaceUtils 全局缓存（RegisterSurface），同时初始化 APS（Advanced Power Saving）插件。

WEAK_ALIAS 声明：内部函数名（如 NativeWindowRequestBuffer）通过 __attribute__((weak, alias)) 别名为公开名（OH_NativeWindow_NativeWindowRequestBuffer）。OH_NativeBuffer_IsSupported 检查 width>0、height>0、format 在有效范围内。OH_NativeBuffer_MapAndGetConfig 是 Map + GetConfig 的组合操作，减少一次函数调用开销。OH_NativeBuffer_MapWaitFence 先 Map 再无限等待 sync fence，确保 buffer 数据可用后再返回。

常见风险

只改 NativeWindow 或 NativeBuffer 一侧 API，遗漏对端同步。两者共用色彩空间映射表和错误码，修改一侧时必须检查另一侧。例如修改 OH_NativeWindow_SetColorSpace 的映射逻辑而不检查 OH_NativeBuffer_SetColorSpace，会导致同一色彩空间在两个 API 上返回不同结果。

改公开 API 参数校验或返回值时，影响 XTS 兼容性。特别是错误码变化可能导致上层应用行为异常：应用可能依赖特定的错误码值做分支判断，错误码数值变化或新增错误码类型都会导致应用走错分支。此类问题在单元测试中不易发现，因为单测通常只检查成功路径。

NativeWindowHandleOpt 变参函数参数类型不匹配导致未定义行为：调用方传入类型错误的变参会破坏栈，且编译器无法检查。例如 SET_USAGE 期望 uint64_t* 但传入 int*，在 64 位系统上会读到垃圾数据。这类问题在 debug 构建中可能不暴露，只在特定编译优化级别或特定架构上才触发崩溃。

OH_NativeBuffer_GetMetadataValue 返回的 new uint8_t[] 未被调用方释放，导致内存泄漏。这是 C API 设计的常见问题，文档和头文件注释中必须明确说明所有权。更隐蔽的是，调用方可能假设缓冲区是栈分配或静态分配的，从而根本不尝试释放。

OH_NativeWindow_SetColorSpace/GetColorSpace 的非确定性问题导致跨版本行为不一致。SetColorSpace 写入编码值，GetColorSpace 反向查找可能返回不同枚举项。当多个枚举项映射到相同的编码值时，std::find_if 在 unordered_map 上的返回结果取决于迭代顺序，这是不可控的。

deprecated API 仍被上层使用，删除或改变行为导致回归。deprecated API 的行为必须保持不变直到正式移除。常见的错误是在 deprecated API 中加入新的参数校验或返回新的错误码，虽然意图是改善鲁棒性，但实际上破坏了依赖旧行为的上层代码。

Surface UserData 方式存储 metadata 的编码格式变更导致旧数据无法解析。UserData 是字符串 key-value 对，编码格式变更会影响读写兼容性。如果新版本写入的格式旧版本无法识别，或者旧版本写入的格式新版本解析出错，都会导致色彩空间、HDR 元数据等关键信息丢失。

NativeWindow 内部 bufferCache_ 的线程安全：mutex_ 保护，但 OH_NativeWindow_CleanCache 标记为 non-thread-safe，调用方需自行保证线程安全。OH_NativeWindow_PreAllocBuffers 也是 non-thread-safe 的。在多线程场景下调用这些接口可能导致缓存状态不一致，进而引发 buffer 数据错乱或访问已释放内存。

OH_NativeWindow_NativeWindowFlushBuffer 中 Region 的 rects 为 nullptr 或 rectNumber 为 0 时，使用整个 buffer 作为 damage。这个默认行为变更会影响脏区传递：如果改为不传 damage 而非全 buffer damage，消费端可能跳过合成导致画面不更新；如果改为更严格的校验导致返回错误，上层未处理该错误的代码路径会崩溃。

Ask before / 必须人工确认

• 修改公开 API 函数签名、参数、返回值或错误码时。
• 修改 NativeWindow 默认配置（usage、format、timeout 等）时。
• 修改 OH_NativeWindow_SetColorSpace/GetColorSpace 行为或映射表时。
• 修改 OH_NativeBuffer_SetMetadataValue/GetMetadataValue 的 key 分发逻辑时。
• 新增或删除 NativeWindowOperation 操作码时。
• 修改 deprecated API 的行为时。
• 需要真实设备验证但当前没有设备时。

验证建议

• 基础构建：hb build graphic_surface -i
• 近端单测：native_window_test、native_buffer_test
• 系统测试：native_window_test_st、native_window_buffer_test_st、native_window_clean_cache_test_st
• Fuzz：NativeWindowFuzzTest、NativeBufferFuzzTest
• 涉及公开 API 行为变化时需要补充对应 XTS 用例。
• 涉及 Surface/DMA/HDI 行为时需要真实设备验证。

待补充背景

deprecated API 依赖情况与迁移时间表

已 deprecated API（根据代码注释）：

• OH_NativeWindow_CreateNativeWindow（deprecated since 12，替代：OH_NativeWindow_CreateNativeWindowFromSurfaceId）
• OH_NativeWindow_NativeWindowSetScalingMode（deprecated since 10，替代：OH_NativeWindow_NativeWindowSetScalingModeV2）
• OH_NativeWindow_NativeWindowSetMetaData/NativeWindowSetMetaDataSet（deprecated since 10）
• SET_STRIDE/GET_STRIDE（deprecated since 16，operation code 6/7）

依赖情况（待团队补充）：

• 上层模块（RS、multimedia、window_manager）对 deprecated API 的实际调用情况
• 第三方应用对 deprecated API 的依赖情况
• 迁移时间表：何时正式移除 deprecated API

兼容性要求：

• deprecated API 必须保持原有行为直到正式移除
• 不能在 deprecated API 中新增参数校验或改变返回值
• 新代码必须使用替代 API，避免引入新的 deprecated 依赖

迁移建议：

• CreateNativeWindow → CreateNativeWindowFromSurfaceId：避免直接暴露 Surface 指针
• NativeWindowSetScalingMode → NativeWindowSetScalingModeV2：使用扩展版本
• NativeWindowSetMetaData → SetMetadataValue：使用标准化 metadata API

XTS 用例映射与覆盖范围

本仓单测/fuzz：

• native_window_test：NativeWindow API 单测
• native_buffer_test：NativeBuffer API 单测
• NativeWindowFuzzTest：NativeWindow fuzz 测试
• NativeBufferFuzzTest：NativeBuffer fuzz 测试

系统测试：

• native_window_test_st：NativeWindow 系统测试
• native_window_buffer_test_st：NativeBuffer 系统测试
• native_window_clean_cache_test_st：缓存清理系统测试

XTS 覆盖范围（待团队补充）：

• OpenHarmony XTS 仓中对应 graphic_surface 的测试用例
• 公开 C API（OH_NativeWindow_/OH_NativeBuffer_）的 XTS 用例映射
• 色彩空间、HDR metadata、usage/format 配置的 XTS 用例
• 错误码兼容性 XTS 用例

验证建议：

• 涉及公开 API 变化时，必须确认 XTS 用例是否需要同步修改
• 新增公开 API 时，必须补充对应 XTS 用例
• 错误码数值变化时，必须检查 XTS 断言是否依赖错误码值

API 兼容性与缓存典型案例（待团队补充案例编号）

错误码映射问题：

• GSError 比较运算符只比较基码（除以 LOWERROR_MAX=1000），不同 low error 的同类错误被视为相等
• 上层应用可能依赖特定错误码数值做分支判断，数值变化导致应用走错分支
• 新增错误码类型时，上层未处理导致默认错误处理逻辑执行

变参函数参数类型问题：

• NativeWindowHandleOpt 变参函数，编译器无法检查参数类型
• SET_USAGE 期望 uint64_t* 但传入 int*，在 64 位系统上读到垃圾数据
• 参数类型错误导致栈破坏，只在特定优化级别或架构上触发崩溃

buffer 缓存一致性问题：

• bufferCache_ 在 RequestBuffer 时缓存 buffer+fence，后续调用直接从缓存返回
• 缓存命中时只更新 fence 不重新传输 buffer 数据，跨进程场景下数据可能不一致
• CleanCache 标记为 non-thread-safe，多线程调用可能导致缓存状态混乱
• 进程死亡后缓存未正确清理，导致后续 RequestBuffer 返回已释放的 buffer

色彩空间非确定性问题：

• SetColorSpace 写入编码值，GetColorSpace 反向查找可能返回不同枚举项
• 多个枚举项映射到相同编码值时，std::find_if 在 unordered_map 上返回不确定结果
• 跨版本行为不一致：同一应用在不同运行可能得到不同色彩空间值