## NVIDIA DRIVE OS Linux SDK API Reference

#### 5.1.12.0 Release

Name

Name Strings

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

New Types

None

New Functions

EGLBoolean eglQueryDisplayAttribNV(
EGLDisplay   dpy,
EGLint       attribute,
EGLAttrib*   value);

EGLDisplay   dpy,
EGLStreamKHR stream,
EGLint       n,
EGLint       offset,
EGLint       size,
const void*  data);

EGLDisplay   dpy,
EGLStreamKHR stream,
EGLenum      name,
EGLint       n,
EGLint       offset,
EGLint       size,
void*        data);

New Tokens

Accepted as <attribute> by eglQueryDisplayAttribNV:

Accepted as <name> by eglQueryStreamMetatdataNV:

Accepted in <attrib_list> by eglCreateStreamKHR and as <attribute>
by eglQueryStreamKHR:

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

------------------------  ----------   ------   ----------

Add new subsections to section "3.10.4 EGLStream Attributes" of
EGL_KHR_stream

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
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.

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

Add new section to "3.10 EGLStreams" of EGL_KHR_stream

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

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
- An EGL_BAD_PARAMETER error is generated if <offset> or <size>
are negative, or if <offset>+<size> is greater than the value

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

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
most recently inserted into the stream by the producer. If <name> is
most recently acquired by the consumer. If <name> is
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
- An EGL_BAD_PARAMETER error is generated if <n> is negative or
is equal to or greater than the value of
- An EGL_BAD_PARAMETER error is generated if <offset> or <size>
are negative, or if <offset>+<size> is greater than the value

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

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

#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.