1Name 2 3 NV_stream_metadata 4 5Name Strings 6 7 EGL_NV_stream_metadata 8 9Contributors 10 11 Daniel Kartch 12 Gajanan Bhat 13 Laszlo Weber 14 Lawrence Ibarria 15 Miguel A. Vico 16 17Contacts 18 19 Daniel Kartch, NVIDIA (dkartch 'at' nvidia 'dot' com) 20 21Status 22 23 Complete 24 25Version 26 27 Version 8 - July 31, 2015 28 29Number 30 31 EGL Extension #93 32 33 34Extension Type 35 36 EGL display extension 37 38Dependencies 39 40 Requires EGL_KHR_stream 41 42 Interacts with EGL_EXT_device_base 43 44Overview 45 46 Application suites which make use of streams to transmit images may 47 need to communicate additional data between the producer and 48 consumer, synchronized with the frame updates. This data may change 49 infrequently, such as a movie title and track number to be displayed 50 to the user, or every frame, such as a focal length and exposure 51 time used to process the image. Transmitting this data outside the 52 scope of the stream may be inconvenient, particularly in the case of 53 cross-process streams. But the nature of the data is highly 54 application-dependent, so it is not feasible for an EGL 55 implementation to define specific extensions for a broad range of 56 application data. 57 58 This extension provides a means for an application (or application 59 suite in the cross-process case) to associate arbitrary metadata 60 with a stream. Multiple metadata fields are available, allowing them 61 to be updated and used independently by separate subcomponents of 62 producers and consumers, respectively. The format of the data is 63 determined by the application, which is responsible for writing and 64 reading it correctly. 65 66New Types 67 68 None 69 70New Functions 71 72 EGLBoolean eglQueryDisplayAttribNV( 73 EGLDisplay dpy, 74 EGLint attribute, 75 EGLAttrib* value); 76 77 EGLBoolean eglSetStreamMetadataNV( 78 EGLDisplay dpy, 79 EGLStreamKHR stream, 80 EGLint n, 81 EGLint offset, 82 EGLint size, 83 const void* data); 84 85 EGLBoolean eglQueryStreamMetadataNV( 86 EGLDisplay dpy, 87 EGLStreamKHR stream, 88 EGLenum name, 89 EGLint n, 90 EGLint offset, 91 EGLint size, 92 void* data); 93 94New Tokens 95 96 Accepted as <attribute> by eglQueryDisplayAttribNV: 97 98 EGL_MAX_STREAM_METADATA_BLOCKS_NV 0x3250 99 EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV 0x3251 100 EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV 0x3252 101 102 Accepted as <name> by eglQueryStreamMetatdataNV: 103 104 EGL_PRODUCER_METADATA_NV 0x3253 105 EGL_CONSUMER_METADATA_NV 0x3254 106 EGL_PENDING_METADATA_NV 0x3328 107 108 Accepted in <attrib_list> by eglCreateStreamKHR and as <attribute> 109 by eglQueryStreamKHR: 110 111 EGL_METADATA0_SIZE_NV 0x3255 112 EGL_METADATA1_SIZE_NV 0x3256 113 EGL_METADATA2_SIZE_NV 0x3257 114 EGL_METADATA3_SIZE_NV 0x3258 115 116 EGL_METADATA0_TYPE_NV 0x3259 117 EGL_METADATA1_TYPE_NV 0x325A 118 EGL_METADATA2_TYPE_NV 0x325B 119 EGL_METADATA3_TYPE_NV 0x325C 120 121 122Add to section "3.3 EGL Queries" 123 124 To query attributes of an initialized display, call 125 126 EGLBoolean eglQueryDisplayAttribNV( 127 EGLDisplay dpy, 128 EGLint attribute, 129 EGLAttrib* value) 130 131 On success, EGL_TRUE is returned, and the value associated with 132 attribute <name> is returned in <value>. 133 134 If <name> is EGL_MAX_STREAM_METADATA_BLOCKS_NV, the total number 135 of independent metadata blocks supported by each stream is returned. 136 If <name> is EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV, the maximum size 137 supported for an individual metadata block is returned. If <name> is 138 EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV, the maximum combined size of 139 all metadata blocks supported by a single stream is returned. 140 141 On failure, EGL_FALSE is returned. An EGL_BAD_DISPLAY error is 142 generated if <dpy> is not a valid initialized display. An 143 EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid 144 attribute name. 145 146If EGL_EXT_device_base is present, eglQueryDisplayAttribNV is equivalent 147to eglQueryDisplayAttribEXT, and calls to either will return the same 148values. 149 150Add to table "3.10.4.4 EGLStream Attributes" in EGL_KHR_stream 151 152 Attribute Read/Write Type Section 153 ------------------------ ---------- ------ ---------- 154 EGL_METADATA<n>_SIZE_NV io EGLint 3.10.4.x 155 EGL_METADATA<n>_TYPE_NV io EGLint 3.10.4.x+1 156 157Add new subsections to section "3.10.4 EGLStream Attributes" of 158EGL_KHR_stream 159 160 3.10.4.x EGL_METADATA<n>_SIZE_NV 161 162 The EGL_METADATA<n>_SIZE_NV attribute indicates the size of the 163 <n>th metadata block associated with a stream. If <n> is not less 164 than the value of EGL_MAX_STREAM_METADATA_BLOCKS_NV for the parent 165 EGLDisplay, the attribute is treated as unknown. 166 167 These attributes may only be set when the stream is created. The 168 default value is 0. The value may not exceed that of 169 EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV for the parent EGLDisplay. 170 Furthermore, the total size of all metadata blocks may not exceed 171 the value of EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV. If either of 172 these restrictions are exceeded, an EGL_BAD_PARAMETER error is 173 generated. 174 175 3.10.4.x+1 EGL_METADATA<n>_TYPE_NV 176 177 The EGL_METADATA<n>_TYPE_NV attribute indicates an optional 178 application-defined type associated with the stream's <n>th metadata 179 block. If <n> is not less than the value of 180 EGL_MAX_STREAM_METADATA_BLOCKS_NV for the parent EGLDisplay, the 181 attribute is treated as unknown. 182 183 These attributes may only be set when the stream is created. The 184 default value is 0. It is not required that a type be provided for 185 every metadata block for which a size has been specified. These may 186 be used to help separate application components coordinate their use 187 of the stream's metadata blocks. 188 189Add new section to "3.10 EGLStreams" of EGL_KHR_stream 190 191 3.10.y EGLStream metadata 192 193 An application may associate arbitrary blocks of additional data 194 with the stream, to be updated in sync with the frames. The contents 195 and format of these data blocks are left to the application, subject 196 to size restrictions imposed by the implementation. The application 197 must specify the sizes of its metadata blocks at the time the stream 198 is created. The contents may be completely or partially modified 199 every frame or less frequently, as the application chooses. When a 200 new frame is inserted into the stream, a snapshot of the current 201 metadata contents are associated with the frame, and may then be 202 queried from the stream. 203 204 The contents of all metadata blocks of non-zero size are initialized 205 to zeroes. To modify the contents of a portion of a metadata block, 206 call 207 208 EGLBoolean eglSetStreamMetadataNV( 209 EGLDisplay dpy, 210 EGLStreamKHR stream, 211 EGLint n, 212 EGLint offset, 213 EGLint size, 214 const void* data) 215 216 On success, EGL_TRUE is returned and the first <size> bytes pointed 217 to by <data> will be copied to the <n>th metadata block of <stream>, 218 starting at <offset> bytes from the beginning of the block. This 219 data will be associated with all subsequent frames inserted into the 220 stream until the contents are next modified. 221 222 On failure, EGL_FALSE is returned 223 - An EGL_BAD_DISPLAY error is generated if <dpy> is not a valid 224 display. 225 - An EGL_BAD_STREAM_KHR error is generated if <stream> is not a 226 valid stream associated with <dpy>. 227 - An EGL_BAD_STATE_KHR error is generated if the state of 228 <stream> is not EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, 229 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR, or 230 EGL_STREAM_STATE_EMPTY_KHR. 231 - An EGL_BAD_ACCESS error is generated if the producer and 232 consumer endpoints of the stream are represented by separate 233 EGLStream objects, and the producer is not attached to 234 <stream>. 235 - An EGL_BAD_PARAMETER error is generated if <n> is negative or 236 is equal to or greather than the value of 237 EGL_MAX_STREAM_METADATA_BLOCKS_NV for <dpy>. 238 - An EGL_BAD_PARAMETER error is generated if <offset> or <size> 239 are negative, or if <offset>+<size> is greater than the value 240 of EGL_METADATA<n>_SIZE_NV for <stream>. 241 242 If <data> does not point to valid readable memory of at least <size> 243 bytes, undefined behavior will result. If the value of <size> is 244 zero, no error will occur, but the function will have no effect. 245 246 To query the contents of a metadata block for a frame, call 247 248 EGLBoolean eglQueryStreamMetadataNV( 249 EGLDisplay dpy, 250 EGLStreamKHR stream, 251 EGLenum name, 252 EGLint n, 253 EGLint offset, 254 EGLint size, 255 void* data) 256 257 On success, EGL_TRUE is returned and <size> bytes starting from the 258 <offset>th byte of the <n>th metadata block of <stream> will be 259 copied into the memory pointed to by <data>. If <name> is 260 EGL_PRODUCER_METADATA_NV, the metadata will be taken from the frame 261 most recently inserted into the stream by the producer. If <name> is 262 EGL_CONSUMER_METADATA_NV, the metadata will be taken from the frame 263 most recently acquired by the consumer. If <name> is 264 EGL_PENDING_METADATA_NV, the metadata will be taken from the frame 265 which would be obtained if an acquire operation were performed at 266 the time of the query. 267 268 On failure, EGL_FALSE is returned 269 - An EGL_BAD_DISPLAY error is generated if <dpy> is not a valid 270 display. 271 - An EGL_BAD_STREAM_KHR error is generated if <stream> is not a 272 valid stream associated with <dpy>. 273 - An EGL_BAD_STATE_KHR error is generated if the state of 274 <stream> is not EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or 275 EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. 276 - An EGL_BAD_ATTRIBUTE error is generated if <name> is not 277 EGL_PRODUCER_METADATA_NV, EGL_CONSUMER_METADATA_NV, or 278 EGL_PENDING_METADATA_NV. 279 - An EGL_BAD_PARAMETER error is generated if <n> is negative or 280 is equal to or greater than the value of 281 EGL_MAX_STREAM_METADATA_BLOCKS_NV for <dpy>. 282 - An EGL_BAD_PARAMETER error is generated if <offset> or <size> 283 are negative, or if <offset>+<size> is greater than the value 284 of EGL_METADATA<n>_SIZE_NV for <stream>. 285 286 If <data> does not point to valid writeable memory of at least 287 <size> bytes, undefined behavior will result. If the value of <size> 288 is zero, no error will occur, but the function will have no effect. 289 290Issues 291 292 1. What happens if multiple calls are made to 293 eglSetStreamMetadataNV without presenting a new frame? 294 295 RESOLVED: If the calls specify overlapping ranges of the same 296 metadata block, the earlier data in the overlapped portion is 297 overwritten. Only the most recent values are associated with 298 the next frame when it is inserted into the stream. 299 300 2. What happens if multiple frames are presented without calling 301 eglSetStreamMetadataNV? 302 303 RESOLVED: The most recently provided data is reused. 304 305Revision History 306 307 #8 (July 31, 2015) Daniel Kartch 308 - Cleaned up and added contact info for publication. 309 310 #7 (April 2, 2015) Miguel A. Vico 311 - Assigned enumerated value for metadata of pending frame. 312 313 #6 (March 20, 2015) Daniel Kartch 314 - Add query for metadata of pending frame. 315 316 #5 (January 15, 2015) Daniel Kartch 317 - Add paragraph of supported attributes to description of 318 eglQueryDisplayAttribNV. 319 - Added/updated error conditions to set/query functions. 320 - Fixed errors in prototypes. 321 322 #4 (January 6, 2015) Daniel Kartch 323 - Fixed errors in prototypes. 324 - Added enum values. 325 326 #3 (December 12, 2014) Daniel Kartch 327 - Clarified language on how metadata becomes associated with 328 frames inserted into the stream. 329 - Fixed typos. 330 331 #2 (December 12, 2014) Daniel Kartch 332 - Added offset and size to Set and Query functions. 333 334 #1 (December 11, 2014) Daniel Kartch 335 - Initial draft 336