diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt b/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt new file mode 100644 index 0000000..d5a613e --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_metadata.txt @@ -0,0 +1,335 @@ +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 |