Name NV_stream_metadata Name Strings EGL_NV_stream_metadata Contributors Daniel Kartch Gajanan Bhat Laszlo Weber Lawrence Ibarria Miguel A. Vico Contacts Daniel Kartch, NVIDIA (dkartch 'at' nvidia 'dot' com) Status Complete Version Version 8 - July 31, 2015 Number EGL Extension #93 Extension Type EGL display extension Dependencies Requires EGL_KHR_stream Interacts with EGL_EXT_device_base Overview Application suites which make use of streams to transmit images may need to communicate additional data between the producer and consumer, synchronized with the frame updates. This data may change infrequently, such as a movie title and track number to be displayed to the user, or every frame, such as a focal length and exposure time used to process the image. Transmitting this data outside the scope of the stream may be inconvenient, particularly in the case of cross-process streams. But the nature of the data is highly application-dependent, so it is not feasible for an EGL implementation to define specific extensions for a broad range of application data. This extension provides a means for an application (or application suite in the cross-process case) to associate arbitrary metadata with a stream. Multiple metadata fields are available, allowing them to be updated and used independently by separate subcomponents of producers and consumers, respectively. The format of the data is determined by the application, which is responsible for writing and reading it correctly. New Types None New Functions EGLBoolean eglQueryDisplayAttribNV( EGLDisplay dpy, EGLint attribute, EGLAttrib* value); EGLBoolean eglSetStreamMetadataNV( EGLDisplay dpy, EGLStreamKHR stream, EGLint n, EGLint offset, EGLint size, const void* data); EGLBoolean eglQueryStreamMetadataNV( EGLDisplay dpy, EGLStreamKHR stream, EGLenum name, EGLint n, EGLint offset, EGLint size, void* data); New Tokens Accepted as by eglQueryDisplayAttribNV: EGL_MAX_STREAM_METADATA_BLOCKS_NV 0x3250 EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV 0x3251 EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV 0x3252 Accepted as by eglQueryStreamMetatdataNV: EGL_PRODUCER_METADATA_NV 0x3253 EGL_CONSUMER_METADATA_NV 0x3254 EGL_PENDING_METADATA_NV 0x3328 Accepted in by eglCreateStreamKHR and as by eglQueryStreamKHR: EGL_METADATA0_SIZE_NV 0x3255 EGL_METADATA1_SIZE_NV 0x3256 EGL_METADATA2_SIZE_NV 0x3257 EGL_METADATA3_SIZE_NV 0x3258 EGL_METADATA0_TYPE_NV 0x3259 EGL_METADATA1_TYPE_NV 0x325A EGL_METADATA2_TYPE_NV 0x325B EGL_METADATA3_TYPE_NV 0x325C Add to section "3.3 EGL Queries" To query attributes of an initialized display, call EGLBoolean eglQueryDisplayAttribNV( EGLDisplay dpy, EGLint attribute, EGLAttrib* value) On success, EGL_TRUE is returned, and the value associated with attribute is returned in . If is EGL_MAX_STREAM_METADATA_BLOCKS_NV, the total number of independent metadata blocks supported by each stream is returned. If is EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV, the maximum size supported for an individual metadata block is returned. If is EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV, the maximum combined size of all metadata blocks supported by a single stream is returned. On failure, EGL_FALSE is returned. An EGL_BAD_DISPLAY error is generated if is not a valid initialized display. An EGL_BAD_ATTRIBUTE error is generated if is not a valid attribute name. If EGL_EXT_device_base is present, eglQueryDisplayAttribNV is equivalent to eglQueryDisplayAttribEXT, and calls to either will return the same values. Add to table "3.10.4.4 EGLStream Attributes" in EGL_KHR_stream Attribute Read/Write Type Section ------------------------ ---------- ------ ---------- EGL_METADATA_SIZE_NV io EGLint 3.10.4.x EGL_METADATA_TYPE_NV io EGLint 3.10.4.x+1 Add new subsections to section "3.10.4 EGLStream Attributes" of EGL_KHR_stream 3.10.4.x EGL_METADATA_SIZE_NV The EGL_METADATA_SIZE_NV attribute indicates the size of the th metadata block associated with a stream. If is not less than the value of EGL_MAX_STREAM_METADATA_BLOCKS_NV for the parent EGLDisplay, the attribute is treated as unknown. These attributes may only be set when the stream is created. The default value is 0. The value may not exceed that of EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV for the parent EGLDisplay. Furthermore, the total size of all metadata blocks may not exceed the value of EGL_MAX_STREAM_METADATA_TOTAL_SIZE_NV. If either of these restrictions are exceeded, an EGL_BAD_PARAMETER error is generated. 3.10.4.x+1 EGL_METADATA_TYPE_NV The EGL_METADATA_TYPE_NV attribute indicates an optional application-defined type associated with the stream's th metadata block. If is not less than the value of EGL_MAX_STREAM_METADATA_BLOCKS_NV for the parent EGLDisplay, the attribute is treated as unknown. These attributes may only be set when the stream is created. The default value is 0. It is not required that a type be provided for every metadata block for which a size has been specified. These may be used to help separate application components coordinate their use of the stream's metadata blocks. Add new section to "3.10 EGLStreams" of EGL_KHR_stream 3.10.y EGLStream metadata An application may associate arbitrary blocks of additional data with the stream, to be updated in sync with the frames. The contents and format of these data blocks are left to the application, subject to size restrictions imposed by the implementation. The application must specify the sizes of its metadata blocks at the time the stream is created. The contents may be completely or partially modified every frame or less frequently, as the application chooses. When a new frame is inserted into the stream, a snapshot of the current metadata contents are associated with the frame, and may then be queried from the stream. The contents of all metadata blocks of non-zero size are initialized to zeroes. To modify the contents of a portion of a metadata block, call EGLBoolean eglSetStreamMetadataNV( EGLDisplay dpy, EGLStreamKHR stream, EGLint n, EGLint offset, EGLint size, const void* data) On success, EGL_TRUE is returned and the first bytes pointed to by will be copied to the th metadata block of , starting at bytes from the beginning of the block. This data will be associated with all subsequent frames inserted into the stream until the contents are next modified. On failure, EGL_FALSE is returned - An EGL_BAD_DISPLAY error is generated if is not a valid display. - An EGL_BAD_STREAM_KHR error is generated if is not a valid stream associated with . - An EGL_BAD_STATE_KHR error is generated if the state of is not EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR, EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR, or EGL_STREAM_STATE_EMPTY_KHR. - An EGL_BAD_ACCESS error is generated if the producer and consumer endpoints of the stream are represented by separate EGLStream objects, and the producer is not attached to . - An EGL_BAD_PARAMETER error is generated if is negative or is equal to or greather than the value of EGL_MAX_STREAM_METADATA_BLOCKS_NV for . - An EGL_BAD_PARAMETER error is generated if or are negative, or if + is greater than the value of EGL_METADATA_SIZE_NV for . If does not point to valid readable memory of at least bytes, undefined behavior will result. If the value of is zero, no error will occur, but the function will have no effect. To query the contents of a metadata block for a frame, call EGLBoolean eglQueryStreamMetadataNV( EGLDisplay dpy, EGLStreamKHR stream, EGLenum name, EGLint n, EGLint offset, EGLint size, void* data) On success, EGL_TRUE is returned and bytes starting from the th byte of the th metadata block of will be copied into the memory pointed to by . If is EGL_PRODUCER_METADATA_NV, the metadata will be taken from the frame most recently inserted into the stream by the producer. If is EGL_CONSUMER_METADATA_NV, the metadata will be taken from the frame most recently acquired by the consumer. If is EGL_PENDING_METADATA_NV, the metadata will be taken from the frame which would be obtained if an acquire operation were performed at the time of the query. On failure, EGL_FALSE is returned - An EGL_BAD_DISPLAY error is generated if is not a valid display. - An EGL_BAD_STREAM_KHR error is generated if is not a valid stream associated with . - An EGL_BAD_STATE_KHR error is generated if the state of is not EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR or EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. - An EGL_BAD_ATTRIBUTE error is generated if is not EGL_PRODUCER_METADATA_NV, EGL_CONSUMER_METADATA_NV, or EGL_PENDING_METADATA_NV. - An EGL_BAD_PARAMETER error is generated if is negative or is equal to or greater than the value of EGL_MAX_STREAM_METADATA_BLOCKS_NV for . - An EGL_BAD_PARAMETER error is generated if or are negative, or if + is greater than the value of EGL_METADATA_SIZE_NV for . If does not point to valid writeable memory of at least bytes, undefined behavior will result. If the value of is zero, no error will occur, but the function will have no effect. Issues 1. What happens if multiple calls are made to eglSetStreamMetadataNV without presenting a new frame? RESOLVED: If the calls specify overlapping ranges of the same metadata block, the earlier data in the overlapped portion is overwritten. Only the most recent values are associated with the next frame when it is inserted into the stream. 2. What happens if multiple frames are presented without calling eglSetStreamMetadataNV? RESOLVED: The most recently provided data is reused. Revision History #8 (July 31, 2015) Daniel Kartch - Cleaned up and added contact info for publication. #7 (April 2, 2015) Miguel A. Vico - Assigned enumerated value for metadata of pending frame. #6 (March 20, 2015) Daniel Kartch - Add query for metadata of pending frame. #5 (January 15, 2015) Daniel Kartch - Add paragraph of supported attributes to description of eglQueryDisplayAttribNV. - Added/updated error conditions to set/query functions. - Fixed errors in prototypes. #4 (January 6, 2015) Daniel Kartch - Fixed errors in prototypes. - Added enum values. #3 (December 12, 2014) Daniel Kartch - Clarified language on how metadata becomes associated with frames inserted into the stream. - Fixed typos. #2 (December 12, 2014) Daniel Kartch - Added offset and size to Set and Query functions. #1 (December 11, 2014) Daniel Kartch - Initial draft