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