1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
|
Name
NV_stream_origin
Name Strings
EGL_NV_stream_origin
Contributors
Miguel A. Vico
James Jones
Daniel Kartch
Contacts
Miguel A. Vico (mvicomoya 'AT' nvidia.com)
Status
Complete.
Version
Version 5 - May 20, 2019
Number
134
Extension Type
EGL display extension
Dependencies
Requires the EGL_KHR_stream extension.
This extension is written based on the wording of version 26 of the
EGL_KHR_stream extension.
Overview
EGL does not define a frame orientation. However, window systems or
rendering APIs might.
Ideally, when using EGL streams, frame orientation is agreed upon by
both the connected consumer and producer and appropriate handling is
performed within EGL to satisfy both endpoints needs. Thus,
applications will rarely have to worry about frame orientation.
However, in some cases consumer applications such as compositors
might still need to access the frame data as provided by the
consumer. Hence, they need to know what orientation was set for the
stream frames. This will allow applications to adjust the way they
access the frame data.
Similarly, producer applications might need to adjust how rendering
commands are issued depending on the orientation set for the stream
frames.
This extension provides new attributes to allow EGL stream users to
query frame orientation and whether it is handled automatically by
the producer or consumer endpoints so that clients are not required
to take further actions.
New Functions
None.
New Tokens
Accepted as the <attribute> parameter of eglQueryStreamKHR and
eglQueryStreamAttribKHR:
EGL_STREAM_FRAME_ORIGIN_X_NV 0x3366
EGL_STREAM_FRAME_ORIGIN_Y_NV 0x3367
EGL_STREAM_FRAME_MAJOR_AXIS_NV 0x3368
EGL_CONSUMER_AUTO_ORIENTATION_NV 0x3369
EGL_PRODUCER_AUTO_ORIENTATION_NV 0x336A
Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when
attribute is EGL_STREAM_FRAME_ORIGIN_X_NV:
EGL_LEFT_NV 0x336B
EGL_RIGHT_NV 0x336C
Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when
attribute is EGL_STREAM_FRAME_ORIGIN_Y_NV:
EGL_TOP_NV 0x336D
EGL_BOTTOM_NV 0x336E
Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when
attribute is EGL_STREAM_FRAME_MAJOR_AXIS_NV:
EGL_X_AXIS_NV 0x336F
EGL_Y_AXIS_NV 0x3370
Add to table "3.10.4.4 EGLStream Attributes"
Attribute Read/Write Type Section
--------------------------------- ---------- ---------- -----------
EGL_STREAM_FRAME_ORIGIN_X_NV ro EGLint 3.10.4.x
EGL_STREAM_FRAME_ORIGIN_Y_NV ro EGLint 3.10.4.x+1
EGL_STREAM_FRAME_MAJOR_AXIS_NV ro EGLint 3.10.4.x+2
EGL_CONSUMER_AUTO_ORIENTATION_NV ro EGLBoolean 3.10.4.x+3
EGL_PRODUCER_AUTO_ORIENTATION_NV ro EGLBoolean 3.10.4.x+4
Add new subsections to the end of section "3.10.4 EGLStream Attributes"
in EGL_KHR_stream:
3.10.4.x EGL_STREAM_FRAME_ORIGIN_X_NV
EGL_STREAM_FRAME_ORIGIN_X_NV is a read-only attribute that
indicates the position on the X axis of the origin relative to the
stream images surface as agreed upon by consumer and producer.
The relative position on X may be one of the following:
- EGL_LEFT_NV - Coordinates on the X axis will be 0 on the left
border and increase towards the right border until <frame
width> is reached.
- EGL_RIGHT_NV - Coordinates on the X axis will be <frame width>
on the left border and decrease towards the right border until
0 is reached.
- EGL_DONT_CARE - No orientation on the X axis was set by the EGL
implementation. Applications must coordinate what they are
doing.
EGL_STREAM_FRAME_ORIGIN_X_NV will not be defined until a consumer
and a producer are connected to the stream. Querying it before that
will generate an EGL_BAD_STATE_KHR error.
3.10.4.x+1 EGL_STREAM_FRAME_ORIGIN_Y_NV
EGL_STREAM_FRAME_ORIGIN_Y_NV is a read-only attribute that
indicates the position on the Y axis of the origin relative to the
stream images surface as agreed upon by consumer and producer.
The relative position on Y may be one of the following:
- EGL_TOP_NV - Coordinates on the Y axis will be 0 on the top
border and increase towards the bottom border until <frame
height> is reached.
- EGL_BOTTOM_NV - Coordinates on the Y axis will be <frame
height> on the top border and decrease towards the bottom
border until 0 is reached.
- EGL_DONT_CARE - No orientation on the Y axis was set by the EGL
implementation. Applications must coordinate what they are
doing.
EGL_STREAM_FRAME_ORIGIN_Y_NV will not be defined until a consumer
and a producer are connected to the stream. Querying it before that
will generate an EGL_BAD_STATE_KHR error.
3.10.4.x+2 EGL_STREAM_FRAME_MAJOR_AXIS_NV
EGL_STREAM_FRAME_MAJOR_AXIS_NV is a read-only attribute that
indicates whether the stream images are X-major or Y-major.
The major axis may be one of the following:
- EGL_X_AXIS_NV - Frames are laid out such that consecutive
pixels with same Y coordinate reside next to each other in
memory.
- EGL_Y_AXIS_NV - Frames are laid out such that consecutive
pixels with same X coordinate reside next to each other in
memory.
- EGL_DONT_CARE - No major axis was set by the EGL
implementation. Applications must coordinate what they are
doing.
EGL_STREAM_FRAME_MAJOR_AXIS_NV will not be defined until a consumer
and a producer are connected to the stream. Querying it before that
will generate an EGL_BAD_STATE_KHR error.
3.10.4.x+3 EGL_CONSUMER_AUTO_ORIENTATION_NV
EGL_CONSUMER_AUTO_ORIENTATION_NV is a read-only attribute that
indicates whether the consumer endpoint will handle frame orientation
automatically so that the consumer application is not required to
take further actions.
The following values can be returned:
- EGL_TRUE - The consumer application can read frames as normal.
The consumer will flip images as needed if the expected
orientation does not match.
- EGL_FALSE - The consumer application is expected to query the
frame orientation and process images accordingly if it does not
match with the expected orientation.
EGL_CONSUMER_AUTO_ORIENTATION_NV will not be defined until a consumer
and a producer are connected to the stream. Querying it before that
will generate an EGL_BAD_STATE_KHR error.
3.10.4.x+4 EGL_PRODUCER_AUTO_ORIENTATION_NV
EGL_PRODUCER_AUTO_ORIENTATION_NV is a read-only attribute that
indicates whether the producer endpoint will handle frame orientation
automatically so that the producer application is not required to
take further actions.
The following values can be returned:
- EGL_TRUE - The producer application can generate frames as
normal. The producer will flip images as needed if the
expected orientation does not match.
- EGL_FALSE - The producer application is expected to query the
frame orientation and generate images accordingly if it does
not match with the expected orientation.
EGL_PRODUCER_AUTO_ORIENTATION_NV will not be defined until a consumer
and a producer are connected to the stream. Querying it before that
will generate an EGL_BAD_STATE_KHR error.
Add to the error list in section "3.10.4.2 Querying EGLStream
Attributes":
- EGL_BAD_STATE_KHR is generated if <attribute> is any of
EGL_STREAM_FRAME_ORIGIN_X_NV, EGL_STREAM_FRAME_ORIGIN_Y_NV,
EGL_STREAM_FRAME_MAJOR_AXIS_NV, EGL_CONSUMER_AUTO_ORIENTATION_NV,
or EGL_PRODUCER_AUTO_ORIENTATION_NV and the stream is in
EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_CONNECTING_KHR
state.
Issues
1. Frame orientation is only needed for and relevant to specific
consumers and producers. What should the query of either
EGL_STREAM_FRAME_ORIGIN_X_NV, EGL_STREAM_FRAME_ORIGIN_Y_NV,
EGL_STREAM_FRAME_MAJOR_AXIS_NV when consumers or producers that do
not define a frame orientation are connected to the stream?
RESOLVED: If the consumer or producer connected to the stream does
not define a frame orientation, the queries will return
EGL_DONT_CARE and applications must coordinate what they do.
2. What should the query return when the connected consumer or
producer defines a frame orientation but can actually handle any?
RESOLVED: Quering EGL_STREAM_FRAME_ORIGIN_X_NV,
EGL_STREAM_FRAME_ORIGIN_Y_NV, or EGL_STREAM_FRAME_MAJOR_AXIS_NV
will return the default frame orientation.
Querying EGL_CONSUMER_AUTO_ORIENTATION_NV or
EGL_PRODUCER_AUTO_ORIENTATION_NV will return whether the consumer
or producer can handle any orientation automatically so that
applications do not need to worry about it.
If querying EGL_CONSUMER_AUTO_ORIENTATION_NV or
EGL_PRODUCER_AUTO_ORIENTATION_NV returns EGL_FALSE, the
corresponding application is expected to query the frame
orientation and take the appropriate action if that does not match
the expected orientation.
Revision History
#5 (May 20th, 2019) Miguel A. Vico
- Allocate extension number
- Mark extension as complete
#4 (January 30th, 2019) Miguel A. Vico
- Allocate values for added enumerants
- Minor fixes to the major axis attribute description
#3 (October 8th, 2018) Miguel A. Vico
- Collapsed producer and consumer orientation attributes
- Added major axis attribute to fully define orientation
- Added two new attributes to indicate whether the producer or
consumer can handle orientation automatically.
- Rewritten issue #1
- Added issue #2 and its resolution
- Overall spec changes to reflect the above points
#2 (August 19th, 2016) Miguel A. Vico
- Rename newly added attributes as consumer and producer
attributes
- Added both issue #1 and its resolution
- Overall spec changes to reflect the above points
#1 (August 1st, 2016) Miguel A. Vico
- Initial draft
|
