Name NV_stream_frame_limits Name Strings EGL_NV_stream_frame_limits Contributors Daniel Kartch Contacts Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) Status Draft Version Version 4 - October 27, 2016 Number EGL Extension #113 Dependencies Requires EGL_KHR_stream Interacts with EGL_EXT_stream_consumer_egloutput Overview Some stream consumers may allow more than one frame to be acquired at a time, so that applications can operate on sequences of images rather than individual images. This in turn may lead to producers allocating additional buffers to keep the fifo full while fulfilling the consumer's needs. Applications may wish to limit the resources allocated for a given stream, and some stream implementations may be able to operate more efficiently if they know in advance how many buffers will be used. This extension defines two new stream attributes which provide hints as to how many frames the application will require, allowing the implementation to plan accordingly. New functions None New tokens Accepted as an attribute name in the parameter of eglCreateStreamKHR and as the parameter of eglQueryStreamKHR. EGL_PRODUCER_MAX_FRAME_HINT_NV 0x3337 EGL_CONSUMER_MAX_FRAME_HINT_NV 0x3338 Add to "Table 3.10.4.4 EGLStream Attributes" Attribute Read/Write Type Section ------------------------------ ---------- ------ ---------- EGL_PRODUCER_MAX_FRAME_HINT_NV io EGLint 3.10.4.x EGL_CONSUMER_MAX_FRAME_HINT_NV io EGLint 3.10.4.x+1 Add new subsections to section "3.10.4 EGLStream Attributes" 3.10.4.x EGL_PRODUCER_MAX_FRAME_HINT_NV Attribute The EGL_PRODUCER_MAX_FRAME_HINT_NV attribute indicates a limit on how many outstanding frames the producer application intends to have at any given time. This includes all frames currently being generated, waiting in in the stream's mailbox or FIFO, and held by the consumer. Its default value is EGL_DONT_CARE. The implementation may make use of this hint to determine how many buffers or other resources to allocate for the stream. It is not necessarily an error for an application to attempt to insert more than this many frames into the stream at once. However, exceeding available resources may cause a producer to block or return an error, as per its specification. 3.10.4.x+1 EGL_CONSUMER_MAX_FRAME_HINT_NV Attribute The EGL_CONSUMER_MAX_FRAME_HINT_NV attribute indicates a limit on how many frames the consumer application intends to acquire at the same time. Its default value EGL_DONT_CARE. The implementation may make use of this hint to determine how many buffers or other resources to allocate for the stream. It is not necessarily an error for an application to attempt to acquire more than this many frames at once. However, exceeding available resources may cause the consumer or producer to block or return an error, as per their specifications. Add to the description of eglStreamConsumerOutputEXT in the EGL_KHR_stream_consumer_egloutput extension When the producer generates frames faster than the output device can display them, 's EGL_CONSUMER_MAX_FRAME_HINT_NV attribute can be used to throttle the output. No more than the specified number of frames will be scheduled for display at a time. If specified, the value should be set to at least 2, to allow one frame to be displayed while another is acquired and scheduled for display. Issues 1. Is a generic stream extension really necessary, or can such limits instead be imposed in the producer and consumer interfaces? RESOLVED: Yes, it is necessary. There are several use cases where an application may need to impose limits and cannot do so through the producer and consumer interfaces: a) The producer and client interfaces are already published and do not allow room for extension to impose limits. b) The stream is cross-process, and one process needs to impose limits on the endpoint provided by the other process. In addition, a common method for imposing such limits simplifies programming of large application suites which make use of multiple types of producers and consumers, and allows the limits on producer and consumer endpoints to be set to compatible values. 2. Should the attributes be hints or hard limits? RESOLVED: Hints. The variety of possible producers and consumers makes it difficult to specify what the behavior should be if a hard limit is exceeded. The goal here is to allow the application to coordinate its resource requirements with the implementation. If it fails to limit itself to the hinted values, we allow producers or consumers to block or fail as appropriate for their interfaces, but do not require it. Revision History #4 (October 27, 2016) Daniel Kartch - Clean up for publication #3 (September 14, 2106) Daniel Kartch - Switched from hard limits to hints #2 (January 8, 2016) Daniel Kartch - Assigned enum values #1 (October 30, 2015) Daniel Kartch - Initial draft