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

  不是一個有效的

  EGLDIsplay

  handle,那麼将會産生一個

  EGL_BAD_DISPLAY

  的錯誤；

3.9.1 Posting to a Window

推送 buffer 到一個window

EGLBoolean eglSwapBuffers(EGLDisplay dpy,
        EGLSurface surface);
           

如果

surface

是一個

back-buffered

window 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區域大小。