1Name
2
3    NV_stream_flush
4
5Name Strings
6
7    EGL_NV_stream_flush
8
9Contributors
10
11    Santanu Thangaraj
12    Daniel Kartch
13
14Contacts
15
16    Santanu Thangaraj, NVIDIA (sthangaraj 'at' nvidia.com)
17
18Status
19
20    Draft
21
22Version
23
24    Version 3 - April 11, 2018
25
26Number
27
28    127
29
30Extension Type
31
32    EGL display extension
33
34Dependencies
35
36    Requires the EGL_KHR_stream extension.
37
38    Requires either the EGL_KHR_stream_cross_process_fd or 
39    EGL_NV_stream_remote extensions.
40    
41    This extension is written based on the wording of version 27 of 
42    the EGL_KHR_stream extension.
43
44Overview:
45
46    The EGL_KHR_stream_cross_process_fd and EGL_NV_stream_remote 
47    extensions do not guarantee that when the state of the EGLStream
48    object representing one endpoint of the stream changes, 
49    the state of the other endpoint will immediately reflect 
50    that change. Depending on the implementation, there may be some
51    latency in the propagation of state changes.
52
53    This latency will not affect any applications which rely solely
54    on the stream itself for communication. State changes made on 
55    one side will eventually be visible on the other side, 
56    and can then be responded to.
57
58    This only affects applications which use some additional means of 
59    communication outside of the stream itself, which may encounter 
60    race conditions. In particular, if an application inserts a frame
61    into a stream, then sends a message to the other side indicating 
62    that the frame is ready, the other side may encounter an error if
63    it tries to acquire the frame and it is not yet available.
64
65    One solution is to force all operations that change state of one 
66    endpoint to behave synchronously, and not return until the change
67    is reflected on the other endpoint. However this adds undesirable 
68    delays for the majority of applications and operations where such 
69    synchronization is not required. This extension instead provides
70    a means for applications to explicitly invoke such 
71    synchronization only where required.
72
73New types
74
75    None
76
77New Procedures and functions
78
79    EGLBoolean eglStreamFlushNV(
80        EGLDisplay       dpy,
81        EGLStreamKHR     stream); 
82
83New Tokens
84    
85    None
86
87Add a new subsection "3.10.x EGLStream flush" at the end of section 
88"3.10 EGLStreams" in EGL_KHR_stream extension.
89
90    The command
91
92        EGLBoolean eglStreamFlushNV(
93            EGLDisplay       dpy,
94            EGLStreamKHR     stream);
95
96    When called with either producer or consumer endpoint of the 
97    stream, will block until any state changes made to this endpoint 
98    prior to the call are visible on the EGLStream object of the other
99    endpoint.
100
101    On success, EGL_TRUE will be returned. On failure, EGL_FALSE will
102    be returned and an error will be generated.
103
104        - EGL_BAD_STREAM_KHR is generated if <stream> is not a valid
105          EGLStream.
106
107        - EGL_BAD_STATE_KHR is generated if <stream> is in
108          EGL_STREAM_STATE_DISCONNECTED_KHR state.
109
110        - EGL_BAD_DISPLAY is generated if <dpy> is not a valid
111          EGLDisplay.
112
113        - EGL_NOT_INITIALIZED is generated if <dpy> is not initialized.
114
115Issues
116
117    1.  When both producer and consumer are connected to a single 
118        EGLStream object, what happens when eglStreamFlushNV is called?
119
120        RESOLVED: The function returns without any blocking.
121
122Revision History
123
124    #3  (April 11, 2018) Jon Leech
125        - Add missing NV suffix to eglStreamFlushNV
126
127    #2  (April 2, 2018) Santanu Thangaraj
128        - Update based on comments from Daniel Kartch
129        - General cleanup
130
131    #1  (March 26, 2018) Santanu Thangaraj
132        - Initial draft
133