diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt | 472 |
1 files changed, 472 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt b/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt new file mode 100644 index 0000000..c8eb464 --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/NV/EGL_NV_stream_remote.txt @@ -0,0 +1,472 @@ +Name + + NV_stream_remote + NV_stream_cross_object + NV_stream_cross_display + NV_stream_cross_process + NV_stream_cross_partition + NV_stream_cross_system + +Name Strings + + EGL_NV_stream_remote + +Contributors + + Daniel Kartch + Bogdan Naodovic + James Jones + Zander Clucas + +Contacts + + Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) + +Status + + Draft + +Version + + Version 4 - June 01, 2016 + +Number + + EGL Extension #114 + +Extension Type + + EGL display extension + +Dependencies + + Requires EGL_KHR_stream + + Interacts with EGL_KHR_stream_cross_process_fd + + All EGL_NV_stream_cross_* extensions require EGL_NV_stream_remote, + but are independent of each other. + +Overview + + This extension provides a generic framework for establishing stream + connections when the producer and consumer endpoints are not + associated with the same EGLStream object. The cross-process streams + allowed by the EGL_KHR_stream_cross_process_fd extension are one + example of such a connection. Other potential examples include + streams between objects associated with different EGLDisplays in a + single process, streams between processes residing in separate + virtual machine partitions on a single system, or streams between + entirely separate systems connected via the internet. + + The approach used by EGL_KHR_stream_cross_process_fd has several + drawbacks: + - It creates a new pair of stream creation and query functions + which are specific to both the type of stream and the method + used for communicating the stream's identity. Extending this + methodology would require new pairs of functions for every new + type of stream connection. + - It allows creation of the connected stream objects without any + indication of which side will be the consumer and which will be + the producer. It even allows, although this was probably not + intended, a cross-process stream to be established, but have + both producer and consumer exist in the same process, with the + other process acting as a voyeur that can observe state and + perhaps modify attributes, but not operate on frames. + - The use of file descriptors generated by EGL in one process + and accessed by EGL in another to establish communication has + potential security flaws, and may not be available at all on + some real-time operating systems. + + Rather than implement new connection types using this model, we + propose a more generic approach that does not require a + proliferation of new interfaces and avoids any ambiguities in how + the stream will be used. These extensions can coexist with + EGL_KHR_stream_cross_process_fd, but allow for more control of + stream communication by the applications. + + These extensions provide the framework with which arbitrary stream + object pairs can be established, but by themselves are insufficient + to create such pairs. In addition, a separate extension must be + used to determine the protocol by which the two objects will + communicate. See for example the EGL_NV_stream_socket extension. + + Several optional types of separate stream objects are defined, + with successive levels of remoteness. It should be assumed that + a more remote type will be less efficient in transfering images, + and therefore applications should choose the least remote type + available that is compatible with their use cases. + +New Types + + None + +New Functions + + None + +New Tokens + + Returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_STATE_KHR: + + EGL_STREAM_STATE_INITIALIZING_NV 0x3240 + + Accepted as attribute names in eglCreateStreamKHR, + eglCreateStreamAttribKHR, eglQueryStreamKHR, and + eglQueryStreamAttribKHR: + + EGL_STREAM_TYPE_NV 0x3241 + EGL_STREAM_PROTOCOL_NV 0x3242 + EGL_STREAM_ENDPOINT_NV 0x3243 + + Accepted by eglCreateStreamKHR and eglCreateStreamAttribKHR, and + returned by eglQueryStreamKHR and eglQueryStreamAttribKHR, as value + when attribute is EGL_STREAM_TYPE_NV, EGL_STREAM_PROTOCOL_NV or + EGL_STREAM_ENDPOINT_NV: + + EGL_STREAM_LOCAL_NV 0x3244 + + When EGL_NV_stream_cross_object is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_OBJECT_NV 0x334D + + When EGL_NV_stream_cross_display is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_DISPLAY_NV 0x334E + + When EGL_NV_stream_cross_process is present, accepted as + value for attribute EGL_STREAM_TYPE_NV by eglCreateStreamKHR + and eglCreateStreamAttribKHR. When either + EGL_NV_stream_cross_process or EGL_KHR_stream_cross_process_fd + is present, returned by eglQueryStreamKHR and + eglQueryStreamAttribKHR for attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_PROCESS_NV 0x3245 + + When EGL_NV_stream_cross_partition is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_PARTITION_NV 0x323F + + When EGL_NV_stream_cross_system is present, accepted by + eglCreateStreamKHR and eglCreateStreamAttribKHR and returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR as value for + attribute EGL_STREAM_TYPE_NV: + + EGL_STREAM_CROSS_SYSTEM_NV 0x334F + + If EGL_KHR_stream_cross_process_fd is present, returned by + eglQueryStreamKHR and eglQueryStreamAttribKHR when attribute is + EGL_STREAM_PROTOCOL_NV: + + EGL_STREAM_PROTOCOL_FD_NV 0x3246 + + Accepted by eglCreateStreamKHR and eglCreateStreamAttribKHR, and + returned by eglQueryStreamKHR and eglQueryStreamAttribKHR when + attribute is EGL_STREAM_ENDPOINT_NV: + + EGL_STREAM_PRODUCER_NV 0x3247 + EGL_STREAM_CONSUMER_NV 0x3248 + +Add to "Glossary" of EGL_KHR_stream: + + Local stream + A stream implemented with both consumer and producer attached to a + single EGLStream object. + + Remote stream + A stream implemented with two EGLStream objects that communicate + with each other, with the consumer attached to one object and the + producer attached to the other. + +Add to section "3.10.1 Creating an EGLStream" in EGL_KHR_stream: + + If a remote EGLStream is created, as described in section "3.10.5.x + Remote streams", and is paired with an EGLStream object which has + conflicting values for some attributes, creation will succeed, but + the stream will enter state EGL_STREAM_STATE_DISCONNECTED_KHR once + communication is established. + +Add to list of failures in section "3.10.1 Creating an EGLStream" in +EGL_KHR stream: + + - EGL_BAD_MATCH is generated if the value of any one of the + EGL_STREAM_TYPE_NV, EGL_STREAM_PROTOCOL_NV, or + EGL_STREAM_ENDPOINT_NV attributes is EGL_STREAM_LOCAL_NV and + any other of these attributes is neither EGL_STREAM_LOCAL_NV + nor EGL_DONT_CARE. + +Add to section "3.10.2 Connecting an EGLStream to a consumer" in +EGL_KHR_stream: + + Any function which connects a consumer to an EGLStream will fail and + generate an EGL_BAD_ACCESS error if the value of the EGLStream's + EGL_STREAM_ENDPOINT_NV attribute is EGL_STREAM_PRODUCER_NV. + +Add to section "3.10.3 Connecting an EGLStream to a producer" in +EGL_KHR_stream: + + Any function which connects a producer to an EGLStream will fail and + generate an EGL_BAD_ACCESS error if the value of the EGLStream's + EGL_STREAM_ENDPOINT_NV attribute is EGL_STREAM_CONSUMER_NV. + +Add to "Table 3.10.4.4 EGLStream Attributes" in EGL_KHR_stream: + + Attribute Read/Write Type Section + -------------------------- ---------- ------ ---------- + EGL_STREAM_TYPE_NV io EGLint 3.10.4.x + EGL_STREAM_PROTOCOL_NV io EGLint 3.10.4.x+1 + EGL_STREAM_ENDPOINT_NV io EGLint 3.10.4.x+2 + +Add to beginning of state list in section "3.10.4.3 EGL_STREAM_STATE_KHR +Attribute" in EGL_KHR_stream: + + - EGL_STREAM_STATE_INITIALIZING_NV - The EGLStream object + represents one endpoint of a remote stream and has not yet + established communication with the opposite endpoint. + +Replace the first entry in the state transition table in section +"3.10.4.3 EGL_STREAM_STATE_KHR Attribute" in EGL_KHR_stream: + + -> EGL_STREAM_STATE_INITIALIZING_NV + A new remote EGLStream is created in this state. + + EGL_STREAM_STATE_INITIALIZING_NV -> + EGL_STREAM_STATE_CREATED_KHR + Occurs when a remote EGLStream object establishes communication with + the opposite endpoint. + + -> EGL_STREAM_STATE_CREATED_KHR + A new local EGLStream or EGLStream of undetermined type is created + in this state. + +Add new subsections to the end of section "3.10.4 EGLStream Attributes" +in EGL_KHR_stream: + + 3.10.4.x EGL_STREAM_TYPE_NV Attribute + + The EGL_STREAM_TYPE_NV attribute may be set when the stream + is created, and indicates the type of connection between the + EGLStream objects to which the consumer and producer are attached. + Legal values are EGL_DONT_CARE and EGL_STREAM_LOCAL_NV. The + default value is EGL_DONT_CARE. + + A value of EGL_STREAM_LOCAL_NV indicates that this is a local + stream with both consumer and producer connected to a single + EGLStream object. + + If EGL_DONT_CARE is initially specified, the value of the attribute + will automatically be changed to the appropriate value once both + consumer and producer are attached, depending on the functions used. + + Other possible values for EGL_STREAM_TYPE_NV may be defined by + additional extensions to indicate a remote stream. Where used, + the EGL_STREAM_PROTOCOL_NV attribute must also be set to a + communication protocol compatible with the stream type. + + 3.10.4.x+1 EGL_STREAM_PROTOCOL_NV Attribute + + The EGL_STREAM_PROTOCOL_NV attribute may be set when the stream is + created, and indicates the manner in which communication is + established between the EGLStream objects to which the consumer + and producer are attached. Legal values are EGL_DONT_CARE and + EGL_STREAM_LOCAL_NV. The default value is EGL_DONT_CARE. + + A value of EGL_STREAM_LOCAL_NV indicates that this is a local + stream with both consumer and producer connected to a single + EGLStream object, so no communication protocol is required. + + If EGL_DONT_CARE is initially specified, the value of the attribute + will automatically be changed to the appropriate value once both + consumer and producer are attached, depending on the functions used. + + Other possible values for EGL_STREAM_PROTOCOL_NV may be defined by + additional extensions to indicate the communication protocol to be + used for a remote stream. Not all communication protocols are + compatible with all stream types, and vice versa. If incompatible + types and protocols are specified, an EGL_BAD_MATCH error will be + generated. + + 3.10.4.x+2 EGL_STREAM_ENDPOINT_NV Attribute + + The EGL_STREAM_ENDPOINT_NV attribute may be set when the stream is + created, and indicates the endpoints which will be attached to the + EGLStream object. Legal values are EGL_DONT_CARE, + EGL_STREAM_LOCAL_NV, EGL_STREAM_CONSUMER_NV, and + EGL_STREAM_PRODUCER_NV. The default value is EGL_DONT_CARE. + + A value of EGL_STREAM_LOCAL_NV indicates that this is a local + stream with both consumer and producer connected to a single + EGLStream object. + + A value of EGL_STREAM_CONSUMER_NV indicates that the EGLStream + object represents the consumer side of a remote stream. + + A value of EGL_STREAM_PRODUCER_NV indicates that the EGLStream + object represents the producer side of a remote stream. + + If EGL_DONT_CARE is initially specified, the value of the attribute + will automatically be changed to the appropriate value once both + consumer and producer are attached, depending on the functions used. + +If EGL_NV_stream_cross_object is present, in section 3.10.4.x above, +add EGL_STREAM_CROSS_OBJECT_NV to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_OBJECT_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint is obtained from the same EGLDisplay. + +If EGL_NV_stream_cross_display is present, in section 3.10.4.x above, +add EGL_STREAM_CROSS_DISPLAY_NV to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_DISPLAY_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may be obtained from a different EGLDisplay in the same + process. + +If EGL_NV_stream_cross_process or EGL_NV_stream_cross_process_fd is +present, in section "3.10.4.x" above, add EGL_STREAM_CROSS_PROCESS_NV +to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_PROCESS_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may reside in a separate process. + +If EGL_NV_stream_cross_partition is present, in section 3.10.4.x +above, add EGL_STREAM_CROSS_PARTITION_NV to the list of legal values, +and insert + + A value of EGL_STREAM_CROSS_PARTITION_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may reside in a separate virtual machine partition on + the same system. The partitions are not required to be using the + same operating systems, but must support compatible communication + protocols. + +If EGL_NV_stream_cross_system is present, in section 3.10.4.x above, +add EGL_STREAM_CROSS_SYSTEM_NV to the list of legal values, and insert + + A value of EGL_STREAM_CROSS_SYSTEM_NV indicates that the stream + object represents one endpoint of a remote stream whose other + endpoint may reside on an independent hardware system with no + directly sharable memory resources. + +If EGL_KHR_stream_cross_process_fd is present, in section 3.10.4.x+1 +above, add EGL_STREAM_PROTOCOL_FD_NV to the list of legal values, and +insert + + A value of EGL_STREAM_PROTOCOL_FD_NV indicates that the stream is + a remote stream whose communication is established using a file + descriptor. The details of what this file descriptor represents + are implementation dependent. If the EGL_STREAM_PROTOCOL_NV + attribute is initialized with this value, the EGL_STREAM_TYPE_NV + attribute must specify a value of EGL_STREAM_CROSS_PROCESS_NV or + an EGL_BAD_MATCH failure is generated. + + If an initial value of EGL_DONT_CARE is specified and a file + descriptor is subsequently obtained with + eglGetStreamFileDescriptorKHR, the value will be automatically + changed to EGL_STREAM_PROTOCOL_FD_NV. + +Add a new subsection to the end of "3.10.5 EGLStream operation": + + 3.10.5.x Remote streams + + An EGLStream object may be created as the endpoint of a remote + stream by specifying EGL_STREAM_PRODUCER_NV or + EGL_STREAM_CONSUMER_NV as the value for its EGL_STREAM_ENDPOINT_NV + attribute. Valid and compatible EGL_STREAM_TYPE_NV and + EGL_STREAM_PROTOCOL_NV values other than EGL_DONT_CARE or + EGL_STREAM_LOCAL_NV must also be specified. + + If a value for EGL_STREAM_ENDPOINT_NV is not specified, the stream + is assumed to be local, but other extensions (see for example + EGL_KHR_stream_cross_process_fd) may allow it to be converted to a + remote stream before the producer has been attached. + + When an EGLStream object is created as remote, any unspecified + attribute will be initially set to a value of EGL_DONT_CARE. Pairs + of EGLStream objects representing opposite endpoints of a stream are + not required to specify the same attribute lists, but their + attributes must be compatible. When communication is established + between the endpoints, they will exchange attribute settings: + - If both endpoints have a value of EGL_DONT_CARE for an + attribute, the default value will be assigned. + - If one endpoint has a value of EGL_DONT_CARE for an attribute, + it will be set to the other endpoint's value. + - If neither endpoint has a value of EGL_DONT_CARE for an + attribute, their values must agree. In most cases, this means + the values must be identical, but this may not be true for all + attributes. In particular, one endpoint must specify an + EGL_STREAM_ENDPOINT_NV value of EGL_STREAM_CONSUMER_NV, and + the other must specify a value of EGL_STREAM_PRODUCER_NV. + If the values for any attribute are not compatible, the stream will + transition to the EGL_STREAM_STATE_DISCONNECTED_KHR state. + + Additionally, if the two EGLStream objects representing a remote + stream are created for EGLDisplays which cannot share resources, + the stream will transition to the EGL_STREAM_STATE_DISCONNECTED_KHR + state. + + When using remote streams, there may be latency in communicating + state changes between the EGLStream objects representing the two + endpoints. For instance, when a new frame is inserted into the + stream by the producer, the consumer endpoint may not immediately + transition to EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR. Similarly, + when a frame is acquired by the consumer, the producer endpoint may + not immediately transition to + EGL_STREAM_STATE_OLD_FRAME_AVAILABLE_KHR. Applications should rely + only on the state of the endpoint on which they are operating to + determine the expected results of that operation. + +In section "3.10.1.1 Duplicating an EGLStream from a file descriptor" of +the EGL_KHR_stream_cross_process_fd extension, add to the failure list +for eglGetStreamFileDescriptor + + - EGL_BAD_ACCESS is generated if the EGL_STREAM_TYPE_NV + attribute of <stream> is anything other than EGL_DONT_CARE or + EGL_STREAM_CROSS_PROCESS_NV. + + - EGL_BAD_ACCESS is generated if the EGL_STREAM_PROTOCOL_NV + attribute of <stream> is anything other than EGL_DONT_CARE or + EGL_STREAM_PROTOCOL_FD_NV. + + - EGL_BAD_ACCESS is generated if the EGL_STREAM_ENDPOINT_NV + attribute of <stream> is EGL_STREAM_LOCAL_NV. + +Issues + + None + +Revision History + + #4 (June 01, 2016) + - Removed sync object definition. It will be provided by a + separate extension. + - Folded in cross-partition extension. + - Added types for cross-object, cross-display, and + cross-system streams. + - General cleanup in preparation for publication. + + #3 (September 16, 2015) Zander Clucas + - Removed dependence of the CROSS_PROCESS type on the + EGL_NV_cross_process_fd extension + - Added CROSS_PROCESS to the list of STREAM_TYPE legal values + - Added CROSS_PROCESS requirement for cross_process_fd protocol + + #2 (December 11, 2014) Daniel Kartch + - Rewrote as NV draft for earlier release. + - Added section for creation of sync object. + - Reserved enum values. + + #1 (October 10, 2014) Daniel Kartch + - Initial EXT draft |