1Name
2
3    ANDROID_recordable
4
5Name Strings
6
7    EGL_ANDROID_recordable
8
9Contributors
10
11    Jamie Gennis
12
13Contact
14
15    Jamie Gennis, Google Inc. (jgennis 'at' google.com)
16
17Status
18
19    Complete
20
21Version
22
23    Version 2, July 15, 2011
24
25Number
26
27    EGL Extension #51
28
29Dependencies
30
31    Requires EGL 1.0
32
33    This extension is written against the wording of the EGL 1.4 Specification
34
35Overview
36
37    Android supports a number of different ANativeWindow implementations that
38    can be used to create an EGLSurface.  One implementation, which records the
39    rendered image as a video each time eglSwapBuffers gets called, may have
40    some device-specific restrictions.  Because of this, some EGLConfigs may be
41    incompatible with these ANativeWindows.  This extension introduces a new
42    boolean EGLConfig attribute that indicates whether the EGLConfig supports
43    rendering to an ANativeWindow that records images to a video.
44
45New Types
46
47    None.
48
49New Procedures and Functions
50
51    None.
52
53New Tokens
54
55    Accepted by the <attribute> parameter of eglGetConfigAttrib and
56    the <attrib_list> parameter of eglChooseConfig:
57
58        EGL_RECORDABLE_ANDROID                      0x3142
59
60Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
61
62    Section 3.4, Configuration Management, add a row to Table 3.1.
63
64              Attribute             Type                 Notes
65        ----------------------     -------     --------------------------
66        EGL_RECORDABLE_ANDROID     boolean     whether video recording is
67                                               supported
68
69    Section 3.4, Configuration Management, add a row to Table 3.4.
70
71              Attribute            Default     Selection  Sort   Sort
72                                               Criteria   Order  Priority
73        ----------------------  -------------  ---------  -----  --------
74        EGL_RECORDABLE_ANDROID  EGL_DONT_CARE    Exact    None
75
76    Section 3.4, Configuration Management, add a paragraph at the end of the
77    subsection titled Other EGLConfig Attribute Descriptions.
78
79        EGL_RECORDABLE_ANDROID is a boolean indicating whether the config may
80        be used to create an EGLSurface from an ANativeWindow that is a video
81        recorder as indicated by the NATIVE_WINDOW_IS_VIDEO_RECORDER query on
82        the ANativeWindow.
83
84    Section 3.4.1, Querying Configurations, change the last paragraph as follow
85
86        EGLConfigs are not sorted with respect to the parameters
87        EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_CONFORMANT,
88        EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL,
89        EGL_MIN_SWAP_INTERVAL, EGL_RENDERABLE_TYPE, EGL_SURFACE_TYPE,
90        EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE,
91        EGL_TRANSPARENT_GREEN_VALUE, EGL_TRANSPARENT_BLUE_VALUE, and
92        EGL_RECORDABLE_ANDROID.
93
94Issues
95
96    1. Should this functionality be exposed as a new attribute or as a bit in
97    the EGL_SURFACE_TYPE bitfield?
98
99    RESOLVED: It should be a new attribute.  It does not make sense to use up a
100    bit in the limit-size bitfield for a platform-specific extension.
101
102    2. How should the new attribute affect the sorting of EGLConfigs?
103
104    RESOLVED: It should not affect sorting.  Some implementations may not have
105    any drawback associated with using a recordable EGLConfig.  Such
106    implementations should not have to double-up some of their configs to  one
107    sort earlier than .  Implementations that do have drawbacks can use the
108    existing caveat mechanism to report this drawback to the client.
109
110    3. How is this extension expected to be implemented?
111
112    RESPONSE: There are two basic approaches to implementing this extension
113    that were considered during its design.  In both cases it is assumed that a
114    color space conversion must be performed at some point because most video
115    encoding formats use a YUV color space.  The two approaches are
116    distinguished by the point at which this color space conversion is
117    performed.
118
119    One approach involves performing the color space conversion as part of the
120    eglSwapBuffers call before queuing the rendered image to the ANativeWindow.
121    In this case, the VisualID of the EGLConfig would correspond to a YUV
122    Android HAL pixel format from which the video encoder can read.  The
123    EGLConfig would likely have the EGL_SLOW_CONFIG caveat because using that
124    config to render normal window contents would result in an RGB -> YUV color
125    space conversion when rendering the frame as well as a YUV -> RGB
126    conversion when compositing the window.
127
128    The other approach involves performing the color space conversion in the
129    video encoder.  In this case, the VisualID of the EGLConfig would
130    correspond to an RGB HAL pixel format from which the video encoder can
131    read.  The EGLConfig would likely not need to have any caveat set, as using
132    this config for normal window rendering would not have any added cost.
133
134Revision History
135
136#2 (Jamie Gennis, July 15, 2011)
137    - Added issue 3.
138
139#1 (Jamie Gennis, July 8, 2011)
140    - Initial draft.
141