| 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 <attribute> 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 <name> by eglQueryStreamMetatdataNV: |
| |
| EGL_PRODUCER_METADATA_NV 0x3253 |
| EGL_CONSUMER_METADATA_NV 0x3254 |
| EGL_PENDING_METADATA_NV 0x3328 |
| |
| Accepted in <attrib_list> by eglCreateStreamKHR and as <attribute> |
| 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 <name> is returned in <value>. |
| |
| If <name> is EGL_MAX_STREAM_METADATA_BLOCKS_NV, the total number |
| of independent metadata blocks supported by each stream is returned. |
| If <name> is EGL_MAX_STREAM_METADATA_BLOCK_SIZE_NV, the maximum size |
| supported for an individual metadata block is returned. If <name> 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 <dpy> is not a valid initialized display. An |
| EGL_BAD_ATTRIBUTE error is generated if <name> 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<n>_SIZE_NV io EGLint 3.10.4.x |
| EGL_METADATA<n>_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<n>_SIZE_NV |
| |
| The EGL_METADATA<n>_SIZE_NV attribute indicates the size of the |
| <n>th metadata block associated with a stream. If <n> 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<n>_TYPE_NV |
| |
| The EGL_METADATA<n>_TYPE_NV attribute indicates an optional |
| application-defined type associated with the stream's <n>th metadata |
| block. If <n> 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 <size> bytes pointed |
| to by <data> will be copied to the <n>th metadata block of <stream>, |
| starting at <offset> 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 <dpy> is not a valid |
| display. |
| - An EGL_BAD_STREAM_KHR error is generated if <stream> is not a |
| valid stream associated with <dpy>. |
| - An EGL_BAD_STATE_KHR error is generated if the state of |
| <stream> 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 |
| <stream>. |
| - An EGL_BAD_PARAMETER error is generated if <n> is negative or |
| is equal to or greather than the value of |
| EGL_MAX_STREAM_METADATA_BLOCKS_NV for <dpy>. |
| - An EGL_BAD_PARAMETER error is generated if <offset> or <size> |
| are negative, or if <offset>+<size> is greater than the value |
| of EGL_METADATA<n>_SIZE_NV for <stream>. |
| |
| If <data> does not point to valid readable memory of at least <size> |
| bytes, undefined behavior will result. If the value of <size> 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 <size> bytes starting from the |
| <offset>th byte of the <n>th metadata block of <stream> will be |
| copied into the memory pointed to by <data>. If <name> is |
| EGL_PRODUCER_METADATA_NV, the metadata will be taken from the frame |
| most recently inserted into the stream by the producer. If <name> is |
| EGL_CONSUMER_METADATA_NV, the metadata will be taken from the frame |
| most recently acquired by the consumer. If <name> 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 <dpy> is not a valid |
| display. |
| - An EGL_BAD_STREAM_KHR error is generated if <stream> is not a |
| valid stream associated with <dpy>. |
| - An EGL_BAD_STATE_KHR error is generated if the state of |
| <stream> 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 <name> is not |
| EGL_PRODUCER_METADATA_NV, EGL_CONSUMER_METADATA_NV, or |
| EGL_PENDING_METADATA_NV. |
| - An EGL_BAD_PARAMETER error is generated if <n> is negative or |
| is equal to or greater than the value of |
| EGL_MAX_STREAM_METADATA_BLOCKS_NV for <dpy>. |
| - An EGL_BAD_PARAMETER error is generated if <offset> or <size> |
| are negative, or if <offset>+<size> is greater than the value |
| of EGL_METADATA<n>_SIZE_NV for <stream>. |
| |
| If <data> does not point to valid writeable memory of at least |
| <size> bytes, undefined behavior will result. If the value of <size> |
| 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 |
