EGL函数翻译--eglCreatePbufferFromClientBuffer

本文主要是介绍EGL函数翻译--eglCreatePbufferFromClientBuffer，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

EGL函数翻译–eglCreatePbufferFromClientBuffer

函数名

EGLSurface eglCreatePbufferFromClientBuffer(EGLDisplay display,EGLenum buftype,EGLClientBuffer buffer,EGLConfig config,EGLint const * attrib_list);

参数描述

display
指定 EGL 显示连接。

buftype
指定要绑定的客户端 API 缓冲区的类型。必须是 EGL_OPENVG_IMAGE，对应于 OpenVG 的 VGImage 缓冲区。

buffer
指定要绑定的 VGImage 缓冲区的 OpenVG 句柄。

config
指定定义表面可用的帧缓冲区资源的 EGL 帧缓冲区配置。

attrib_list
指定像素缓冲区表面的属性。可以为 NULL 或为空（第一个属性为 EGL_NONE）。

详细描述

eglCreatePbufferFromClientBuffer 创建一个离屏的像素缓冲区表面并返回其句柄。如果创建失败，将返回 EGL_NO_SURFACE。

新创建的像素缓冲区表面类似于通过 eglCreatePbufferSurface 创建的像素缓冲区表面，但颜色缓冲区的存储由客户端 API 缓冲区提供。config 所需的其他缓冲区（如深度缓冲区、模板缓冲区和 alpha 遮罩）由 EGL 分配。

buftype 必须为 EGL_OPENVG_IMAGE，对应于 OpenVG 的 VGImage 缓冲区。buffer 必须是当前 OpenVG 上下文中有效的 VGImage 句柄，并转换为 EGLClientBuffer 类型。

生成的表面的高度、宽度、OpenVG alpha 格式和 OpenVG 色彩空间（分别为表面属性 EGL_HEIGHT、EGL_WIDTH、EGL_VG_ALPHA_FORMAT 和 EGL_VG_COLORSPACE）由 buffer 的大小和格式决定。

表面属性以属性-值对列表的形式指定，以 EGL_NONE 结束。接受的属性包括：

EGL_MIPMAP_TEXTURE
指定是否应为 mipmap 分配存储空间。如果属性值为 EGL_TRUE 且 EGL_TEXTURE_FORMAT 不是 EGL_NO_TEXTURE，则会为 mipmap 预留空间。默认值为 EGL_FALSE。

EGL_TEXTURE_FORMAT
指定在将像素缓冲区绑定到纹理映射时将创建的纹理的格式。可能的值为 EGL_NO_TEXTURE、EGL_TEXTURE_RGB 和 EGL_TEXTURE_RGBA。默认值为 EGL_NO_TEXTURE。

EGL_TEXTURE_TARGET
指定在使用 EGL_TEXTURE_RGB 或 EGL_TEXTURE_RGBA 纹理格式创建的像素缓冲区的目标。可能的值为 EGL_NO_TEXTURE 或 EGL_TEXTURE_2D。默认值为 EGL_NO_TEXTURE。

任何使用 config 创建的 EGL 渲染上下文都可以用于渲染到该表面上。使用 eglMakeCurrent 将 EGL 渲染上下文附加到该表面。

使用 eglQuerySurface 检索已分配的像素缓冲区表面的尺寸或 config 的 ID。

使用 eglDestroySurface 销毁表面。

注意

eglCreatePbufferFromClientBuffer 仅在 EGL 版本为 1.2 或更高版本时受支持，并且要求 EGL 实现支持 OpenVG 客户端 API。

当前 eglCreatePbufferFromClientBuffer 仅支持将 OpenVG VGImage 缓冲区绑定到像素缓冲区。虽然未来可能支持其他客户端 API 资源，但像 OpenGL ES 帧缓冲区对象以及用于定义和使用 EGLImageKHR 图像的 EGL 和客户端 API 扩展家族是满足大多数相同需求的更灵活和通用的框架。

如果 config 属性 EGL_TEXTURE_FORMAT 的值不是 EGL_NO_TEXTURE，则像素缓冲区的宽度和高度指定零级纹理图像的大小。

如果指定了 EGL_LARGEST_PBUFFER，并且像素缓冲区将用作纹理（即 EGL_TEXTURE_TARGET 的值为 EGL_TEXTURE_2D 且 EGL_TEXTURE_FORMAT 的值为 EGL_TEXTURE_RGB 或 EGL_TEXTURE_RGBA），则将保留宽高比，且新的宽度和高度将为该纹理目标的有效大小（例如，如果底层 OpenGL ES 实现不支持非 2 的幂大小的纹理，则宽度和高度都将是 2 的幂）。

当将纹理渲染到像素缓冲区并切换要渲染的纹理图像（例如，从渲染一个 mipmap 级别切换到渲染另一个 mipmap 级别）时，深度缓冲区和模板缓冲区的内容可能不会被保留。

将客户端 API 缓冲区绑定到 EGL 像素缓冲区会产生竞态条件，并可能导致缓冲区在一个 API 中仍在使用时通过另一个 API 被删除。为避免这些问题，适用于绑定客户端 API 缓冲区的若干限制如下：

绑定的缓冲区只能由 EGL 或创建它的客户端 API 独占使用。例如，如果一个 VGImage 绑定到一个像素缓冲区，并且该像素缓冲区绑定到任何客户端 API 渲染上下文，那么 VGImage 不能作为任何 OpenVG 操作的显式源或目标。此类使用的错误在客户端 API 规范中描述。同样，当 VGImage 由 OpenVG 使用时，绑定到它的像素缓冲区不能通过 eglMakeCurrent 绑定到任何客户端 API 上下文。

绑定缓冲区会创建对它的额外引用，实现必须在销毁对象时尊重未完成的引用。例如，如果 VGImage 绑定到一个像素缓冲区，使用 vgDestroyImage 销毁该图像不会释放底层缓冲区，因为 EGL 仍在使用它。然而，在 vgDestroyImage 之后，缓冲区只能通过 EGL 像素缓冲区句柄引用，因为 OpenVG 对该缓冲区的句柄不再存在。同样，使用 eglDestroySurface 销毁像素缓冲区不会释放底层缓冲区，因为 OpenVG 仍在使用它。然而，在 eglDestroySurface 之后，缓冲区只能通过 OpenVG 的 VGImage 句柄引用，因为 EGL 的像素缓冲区句柄不再存在。

错误描述

如果上下文创建失败，返回 EGL_NO_SURFACE。

如果 display 不是一个 EGL 显示连接，生成 EGL_BAD_DISPLAY 错误。

如果 display 尚未初始化，生成 EGL_NOT_INITIALIZED 错误。

如果 config 不是一个 EGL 帧缓冲区配置，生成 EGL_BAD_CONFIG 错误。

如果 buftype 不是 EGL_OPENVG_IMAGE，或者 buffer 不是当前绑定的 OpenVG 上下文中的有效 VGImage 对象句柄，生成 EGL_BAD_PARAMETER 错误。

如果没有当前的 OpenVG 上下文，或者如果 buffer 已经绑定到另一个像素缓冲区或正如上面的注意事项中讨论的那样正在被 OpenVG 使用，生成 EGL_BAD_ACCESS 错误。

如果 buffer 中包含的缓冲区是任何 EGLImage 兄弟缓冲区的一部分，生成 EGL_BAD_ACCESS 错误。

如果没有足够的资源分配新表面，生成 EGL_BAD_ALLOC 错误。

如果 attrib_list 包含无效的像素缓冲区属性，或者属性值未被识别或超出范围，生成 EGL_BAD_ATTRIBUTE 错误。

如果 attrib_list 包含属性 EGL_MIPMAP_TEXTURE、EGL_TEXTURE_FORMAT 或 EGL_TEXTURE_TARGET，并且 config 不支持 OpenGL ES 渲染（例如，EGL 版本为 1.2 或更高版本，并且 config 的 EGL_RENDERABLE_TYPE 属性不包括 EGL_OPENGL_ES_BIT 或 EGL_OPENGL_ES2_BIT 之一），生成 EGL_BAD_ATTRIBUTE 错误。

如果 config 不支持渲染到像素缓冲区（EGL_SURFACE_TYPE 属性不包含 EGL_PBUFFER_BIT），生成 EGL_BAD_MATCH 错误。

如果 buffer 中包含的缓冲区与 config 指定的这些缓冲区的位深度不匹配，生成 EGL_BAD_MATCH 错误。

如果 EGL_TEXTURE_FORMAT 属性不是 EGL_NO_TEXTURE，且 EGL_WIDTH 和/或 EGL_HEIGHT 指定的大小无效（例如，纹理大小不是 2 的幂，并且底层 OpenGL ES 实现不支持非 2 的幂大小的纹理），生成 EGL_BAD_MATCH 错误。

如果 EGL_TEXTURE_FORMAT 属性是 EGL_NO_TEXTURE，且 EGL_TEXTURE_TARGET 不是 EGL_NO_TEXTURE，或 EGL_TEXTURE_FORMAT 是 EGL_NO_TEXTURE 之外的其他值，且 EGL_TEXTURE_TARGET 是 EGL_NO_TEXTURE，生成 EGL_BAD_MATCH 错误。

如果实现对可绑定到像素缓冲区表面的客户端 API 缓冲区类型有其他约束，生成 EGL_BAD_MATCH 错误。例如，OpenVG 实现可能不支持将 VGImage 绑定到将用作 mipmapped OpenGL ES 纹理的像素缓冲区（例如，其 EGL_MIPMAP_TEXTURE 属性为 TRUE）。任何此类约束应由实现发布说明记录。