EGL 1.4 API 中文（部分）

工作内容变更，不再更新

写作背景

写这篇学习笔记，出于三个目的：
1. 学习Makrdowm；
2. 了解EGL基本API；
3. 学习英语和熟练翻译；
因为是对EGL大致有个了解，所以一下部分进对关键API参考官方文档进行了翻译。
翻译的不好的地方，大家多包涵。

---

3.4 配置管理

EGLBoolean eglChooseConfig(EGLDisplay dpy, const
    EGLint *attrib_list, EGLConfig *configs,
    EGLint config_size, EGLint *num_config);

得到适配属性列表的EGLConfig配置,返回的configs,soncif_size和num_config的值和意义与eglGetConfigs相同。然而，仅有那些和attrib_list匹配的配置文件才会作为返回。
EGL_FALSE： 函数执行失败；
EGL_BAD_ATTRIBUTE：属性列表中含有未定义的、或者是未能识别、超出范围的特性；
attrib_list后紧跟着期望值，这个列表将以EGL_NONE作为结束标志。如果列表中有得attribute没有别指定值，那么会使用默认值。如果attribute被指定为EGL_DONT_CARE，那么这个属性就不会被检查；除了EGL_LEVE和EGL_MATCH_NATIVE_PIXMAP这两个attribute，其他都可以被设置为EGL_DONT_CARE；
如果attrib_list为NULL或者为空，根据默认优先级选择和排序EGLConfigs工作结束。

3.4.1 选择EGLConfigs

按表3.4中特定属性的方式匹配attribute，表中的标准有如下意义:

• AtLeast仅有那些满足或超过该特定值的EGLConfigs会被选择
• Exact仅有那些与该属性值相等的EGLConfigs会能匹配
• Mak 仅有那些与该属性值mask bit相同的EGLConfigs会被选中
• Special 指定特性的描述

一些特性必须匹配指定确切的值，而其他的，例如EGL_RED_SIZE必须满足或超过指定的最小值。
用唯一整形值ID检索出EGLConfig，使用 EGL_CONFIG_ID特性。
使用EGL_CONFIG_ID特性，给定独有的ID整形值，将会检索出一个唯一的EGLConfig。当EGL_CONFIG_ID已经指定，那么其他所有的特性将会被忽略并且经返回和这个ID相同的EGLConfig。
如果EGL_MAX_PBUFFER_WIDTH,EGL_MAX_PBUFFER_HEIGHT,EGL_MAX_PBUFFER_PIXELS,或是EGL_NATIVE_VISSUAL_ID在attri_list中指定

3.7 渲染描述表

EGLContext eglCreateContext(EGLDisplay dpy,
    EGLConfig config, EGLContext share_context,
    const EGLint *attrib_list);

如果eglCreateContext执行成功，它会初始化这个context为当前渲染支持的API的初始化状态，并且返回对应的handle。任何兼容的EGLSurface都能够使用这个context去做渲染。
虽然context被限定用于单独的客户端API，但是所有在EGL中创建的context都存在于独自的命名空间，因此允许多个EGL调用去管理context避免占用当前正在使用的渲染API。
如果share_context不等于EGL_NO_CONTEXT，那么所有被客户端API定义的可共享数据（注意，限于OpenGLS、OpenGL ES，共享数据除了被命名为0的纹理对象）将会被share_context共享出去,包括已经被共享的和刚被创建的context。EGLContexts中的任意数字都能以这种形式共享。OpenGL和OpenGL ES服务端的contxt（对于所有共享context）必须存在于单一地址空间中，否则会产生一个EGL_BAD_MATCH错误。
attib_list如果为NULL或者为空（以EGL_NONE作为第一个特性），在这种情况下每个特性都将会使用默认值，以下将会说明。
EGL_CONTEST_CLIENT_VERSION用于决定创建哪个版本的OpenGL ES context。
例如，特性值设置为2（默认值为1），那么将会创建一个适用于OpenGL ES 2.0的context。
如果创建失败，将会返回EGL_NO_CONTEXT。如果当前渲染api是EGL_NONE，那么将会产生一个EGL_BAD_MATCH的错误（这个情况尽在设备不支持OpenGL ES或者超前于eglBindAPI下发生）如果share_context不是0也不是客户端API最新创建的一个有效的context，那么将会放回一个EGL_BAD_CONTEXT错误。
如果config不是一个有效的EGLConfig,或者是不被支持的客户端API请求，那么将会产生一个EGL_BAD_CONFIG的错误（包括，当config中不含有特性EGL_OPENGL_ES_BIT,却要创建一个OpenGL ES 1.x的context，或者是，config中不含有特性EGL_OPENGL_ES2_BIT,却要创建一个OpenGL ES 1.x的context）。

以下情况将会返回EGL_BAD_MATCH的错误

• 用于监视share_contet的OpenGL、OpenGL ES的客户端context存在于一个无法被新建的context共享的地址空间；
• share_context创建在另一个显示设备中，而非config中引用的显示设备；
• 不兼容的context（如，一个context关联的是硬件设备驱动，而另一个确实软件渲染器）

如果服务端没有足够的空间用于创建context，那么将会返回一个EGL_BAD_ALLOC的错误。

3.7.3 Binding Contexts and Drawables

 EGLBoolean eglMakeCurrent(EGLDisplay dpy,
        EGLSurface draw, EGLSurface read,
        EGLContext ctx);

eglMakeCurrent将ctx与当前渲染线程、draw/read surface绑定在一起。
对于OpenGL、OpenGL ES的context而言，draw被用于所有的操作除了像素点数据读取或是拷贝，从read这个frame buffer中获取。注意同一个EGLSurface可以同时被指定为draw和read。
对于OpenVG context，‘draw’和read必须是同一个。

• 如果ctx对应其他线程，或者draw或read被绑定到另一个线程中的contexts，那么将会产生给一个EGL_BAD_ACCESS错误。
• 如果绑定的ctx数量超过了当前客户端实例API支持的类型，那么将会产生一个EGL_BAD_ACCESS的错误；
• 如果draw或是read是由eglCreatePbufferFromClinetBuffer创建的pbuffer并且底层绑定的客户端API正是由客户端API创建的，那么将会产生一个EGL_BAD_CONTEXT的错误；
• 如果ctx不是一个有效的context，那么将会产生一个EGL_BAD_CONTEXT的错误；
• 如果draw或是read不是有效的EGL surface，那么那么将产生一个EGL_BAD_SURFACE的错误；
• 如果一个native window中的draw或者read不在有效，那么将会产生一个EGL_BAD_SURFACE的错误；
• 如果draw或是read不能够同事适配图像内存，那么将会产生给一个EGL_BAD_MATCH的错误；
• 如果之前的调用线程的前一个context已经未冲刷掉的命令，并且之前的surface不在有效，那么将会产生一个EGL_BAD_CURRENT_SURFACE的错误；
• 如果不能够申请一个辅助buffer用于draw和read，那么将会产生一个EGL_BAD_ALLOC的错误；
• 如果发生了一个电源管理event，那么将会产生一个EGL_CONTEXT_LOST错误；
• 和其他附带EGLDisplay参数的命令一样，如果dpy不是一个有效的EGLDIsplayhandle,那么将会产生一个EGL_BAD_DISPLAY的错误；

3.9.1 Posting to a Window

推送 buffer 到一个window

EGLBoolean eglSwapBuffers(EGLDisplay dpy,
        EGLSurface surface);

如果surface是一个back-bufferedwindow surface，那么这个buffer将被拷贝到native window。如果surface是一个single-buffered窗口，pixmap、或是pbuffer surface，eglSwapBuffers将不起效。
在调用eglSwapBuffers以后辅助buffer的内容将会一直保持未知状态。如果EGL-SWAP_BEHAVIOR的属性值不是EGL_BUFFER_PRESERVED那么辅助buffer的内容将会是未知的。如section 3.5.6中的描述, 使用eglSurfaceAttrib的surface能够设置EGL_SWAP_BEHAVIOR的值。

3.9.1.1 Native Window Resizing

如果在swap前，相对于surface，native window的大小发生改变，那么surface也必须调整以适配。如果surface大少产生了收缩，那么一些已经绘制的像素点数据将会丢失，如果surface的大小产生了增长，那么新申请的buffer内容将会是不确定的。以上这些大小调整的都是为了保证EGL surface 和native window的一致性；而客户端仅负责识别window的大小改变，进而改变对应的viewprot和scissor区域大小。