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