EGL函数翻译–eglMakeCurrent
函数名
EGLBoolean eglMakeCurrent(EGLDisplay display,
EGLSurface draw,
EGLSurface read,
EGLContext context);
参数描述
display
指定 EGL 显示连接。
draw
指定 EGL 绘图表面。
read
指定 EGL 读取表面。
context
指定要附加到表面的 EGL 渲染上下文。
详细描述
eglMakeCurrent 将上下文绑定到当前渲染线程以及 draw 和 read 表面。
对于 OpenGL 或 OpenGL ES 上下文,draw 用于除像素数据读取或复制(如 glReadPixels、glCopyTexImage2D 和 glCopyTexSubImage2D)之外的所有操作,这些操作会从 read 的帧缓冲区值中获取。请注意,相同的 EGLSurface 可以同时指定为 draw 和 read。
对于 OpenVG 上下文,draw 和 read 必须指定相同的 EGLSurface。
如果调用线程已经有与 context 相同客户端 API 类型的当前渲染上下文,那么该上下文会被刷新并标记为不再是当前上下文。然后,context 被设为调用线程的当前上下文。对于 eglMakeCurrent 的目的,所有 OpenGL ES 和 OpenGL 上下文的客户端 API 类型被视为相同。换句话说,如果当前绑定的是任意 OpenGL ES 上下文,而 context 是 OpenGL 上下文,或者当前绑定的是 OpenGL 上下文而 context 是 OpenGL ES 上下文,那么当前绑定的上下文将不再是当前上下文,而 context 将成为当前上下文。
由例如 glMapBuffer 创建的 OpenGL 和 OpenGL ES 缓冲区映射不会受到 eglMakeCurrent 的影响;它们在缓冲区所属的上下文是否为当前上下文的情况下都会持续存在。
如果 eglMakeCurrent 调用后 draw 被销毁,那么后续的渲染命令将会被处理并更新上下文状态,但表面的内容将变得不确定。如果 read 被销毁,那么从帧缓冲区读取的像素值(如调用 glReadPixels 的结果)将变得不确定。如果销毁了绘图或读取表面所基于的本地窗口或图元,那么渲染和读取操作将按上述情况处理。
要释放当前上下文而不分配新上下文,请将 context 设置为 EGL_NO_CONTEXT 并将 draw 和 read 设置为 EGL_NO_SURFACE。指定的客户端 API 的当前渲染上下文会被刷新并标记为不再是当前上下文,在 eglMakeCurrent 返回后,该客户端 API 将没有当前上下文。这是 eglMakeCurrent 唯一会尊重当前渲染 API 的情况。在所有其他情况下,受影响的客户端 API 由 context 决定。这是唯一可以传递未初始化的 display 给 eglMakeCurrent 的情况。
如果 context 不是 EGL_NO_CONTEXT,那么除非 context 支持在没有 read 和 draw 表面的情况下绑定,否则 draw 和 read 都不能是 EGL_NO_SURFACE。在这种情况下,该上下文在没有默认帧缓冲区的情况下被设为当前上下文。此操作的含义由支持该上下文的客户端 API 定义(参见 OpenGL 3.0 规范的第 4 章,以及 GL_OES_surfaceless_context OpenGL ES 扩展)。
第一次将 OpenGL 或 OpenGL ES 上下文设为当前上下文时,视口和剪裁区域的尺寸会被设置为 draw 表面的大小(如同调用了 glViewport(0,0,w,h) 和 glScissor(0,0,w,h),其中 w 和 h 分别为表面的宽度和高度)。但是,当上下文随后被设为当前上下文时,视口和剪裁区域的尺寸不会被修改。在这种情况下,客户端有责任重设视口和剪裁区域。
第一次将上下文设为当前上下文时,如果没有默认帧缓冲区(例如 draw 和 read 都是 EGL_NO_SURFACE),那么视口和剪裁区域将被设置为 glViewport(0,0,0,0) 和 glScissor(0,0,0,0)。
实现可能会延迟为表面分配辅助缓冲区,直到上下文需要它们(这可能导致出现下面描述的 EGL_BAD_ALLOC 错误)。但是,一旦分配了辅助缓冲区,它们和它们的内容将会持续存在,直到表面被删除。
使用 eglGetCurrentContext、eglGetCurrentDisplay 和 eglGetCurrentSurface 来查询当前渲染上下文和相关的显示连接及表面。
错误描述
如果 draw 或 read 与 context 不兼容,则会生成 EGL_BAD_MATCH 错误。
如果 context 当前在其他线程中,或者 draw 或 read 绑定到其他线程中的上下文,则会生成 EGL_BAD_ACCESS 错误。
如果绑定 context 会超出实现支持的当前上下文数量,则会生成 EGL_BAD_ACCESS 错误。
如果 draw 或 read 是通过 eglCreatePbufferFromClientBuffer 创建的 pbuffer,并且客户端 API 创建时底层绑定的客户端 API 缓冲区正在使用中,则会生成 EGL_BAD_ACCESS 错误。
如果 context 不是有效的上下文且不是 EGL_NO_CONTEXT,则会生成 EGL_BAD_CONTEXT 错误。
如果 draw 或 read 不是有效的 EGL 表面且不是 EGL_NO_SURFACE,则会生成 EGL_BAD_SURFACE 错误。
如果 context 是 EGL_NO_CONTEXT,但 draw 或 read 不是 EGL_NO_SURFACE,则会生成 EGL_BAD_MATCH 错误。
如果 draw 或 read 是有效表面,而另一个是 EGL_NO_SURFACE,则会生成 EGL_BAD_MATCH 错误。
如果 context 不支持在没有 read 和 draw 表面的情况下绑定,而 draw 和 read 都是 EGL_NO_SURFACE,则会生成 EGL_BAD_MATCH 错误。
如果 draw 或 read 所基于的本地窗口不再有效,则会生成 EGL_BAD_NATIVE_WINDOW 错误。
如果 draw 和 read 无法同时放入图形内存中,则会生成 EGL_BAD_MATCH 错误。
如果调用线程的前一个上下文有未刷新的命令,并且前一个表面不再有效,则会生成 EGL_BAD_CURRENT_SURFACE 错误。
如果无法为 draw 和 read 分配辅助缓冲区,则会生成 EGL_BAD_ALLOC 错误。
如果发生了电源管理事件,则会生成 EGL_CONTEXT_LOST 错误。
如果满足以下任一条件:
context 不是 EGL_NO_CONTEXT
read 不是 EGL_NO_SURFACE
draw 不是 EGL_NO_SURFACE
那么如果 display 是一个有效但未初始化的显示,则会生成 EGL_NOT_INITIALIZED 错误。
与其他接受 EGLDisplay 参数的命令一样,如果 display 不是有效的 EGLDisplay 句柄,则会生成 EGL_BAD_DISPLAY 错误。(某些实现选择允许 EGL_NO_DISPLAY 作为 eglMakeCurrent 的有效显示参数。这种行为在所有 EGL 实现中不可移植,应视为未记录的供应商扩展)。
英文连接
链接: https://registry.khronos.org/EGL/sdk/docs/man/