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_sizenum_config的值和意义与eglGetConfigs相同。然而,仅有那些和attrib_list匹配的配置文件才会作为返回。
EGL_FALSE: 函数执行失败;
EGL_BAD_ATTRIBUTE:属性列表中含有未定义的、或者是未能识别、超出范围的特性;
attrib_list后紧跟着期望值,这个列表将以EGL_NONE作为结束标志。如果列表中有得attribute没有别指定值,那么会使用默认值。如果attribute被指定为EGL_DONT_CARE,那么这个属性就不会被检查;除了EGL_LEVEEGL_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_IDattri_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可以同时被指定为drawread
对于OpenVG context,‘draw’和read必须是同一个。

  • 如果ctx对应其他线程,或者drawread被绑定到另一个线程中的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用于drawread,那么将会产生一个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区域大小。

你可能感兴趣的:(Others,EGL,Android)