1Name 2 3 NV_stream_socket 4 NV_stream_socket_unix 5 NV_stream_socket_inet 6 7Name Strings 8 9 EGL_NV_stream_socket 10 EGL_NV_stream_socket_unix 11 EGL_NV_stream_socket_inet 12 13Contributors 14 15 Daniel Kartch 16 Bogdan Naodovic 17 James Jones 18 Zander Clucas 19 Tarun Bansal 20 21Contacts 22 23 Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) 24 25Status 26 27 Draft 28 29Version 30 31 Version 6 - October 27, 2016 32 33Number 34 35 EGL Extension #115 36 37Extension Type 38 39 EGL display extension 40 41Dependencies 42 43 EGL_NV_stream_socket requires EGL_NV_stream_remote. 44 45 EGL_NV_stream_socket_unix requires EGL_NV_stream_socket. 46 47 EGL_NV_stream_socket_inet requires EGL_NV_stream_socket. 48 49Overview 50 51 These extensions build on the framework for remote streams provided 52 in EGL_NV_stream_remote to define a means for two EGLStream objects 53 representing opposite ends of a single stream to establish 54 communication using a socket. The application is expected to create 55 and connnect both ends of the socket before creating the stream 56 objects. 57 58 The base EGL_NV_stream_socket extension defines most of the 59 attributes required to initialize the stream objects. The 60 EGL_NV_stream_socket_unix and EGL_NV_stream_socket_inet extensions 61 indicate support for UNIX domain and internet protocol socket types, 62 respectively. Additional extensions may provide support for other 63 socket types. The type of socket is important, as certain operations 64 are only available with certain types, which may influence how the 65 streams are implemented. For instance, UNIX domain sockets allow 66 file descriptors to be passed between processes, while internet 67 protocol sockets do not. This ability may allow more efficient 68 sharing of resources between the socket endpoints. 69 70 An application using this extension will bear some similarity to the 71 example code from the EGL_KHR_stream_cross_process_fd extension, 72 which also uses sockets to establish the communication between two 73 processes and then create a pair of EGLStream objects. The key 74 difference is that in that case, the sockets are merely a temporary 75 means to an end to pass a file descriptor between the processes. 76 Once that is accomplished, the sockets are discarded. 77 78 The file descriptor used by that extension may represent an 79 underlying object such as shared memory which allows more efficient 80 communication than the sockets themselves. However, there is nothing 81 preventing an implementation of EGL_NV_stream_socket from creating 82 and passing such a file descriptor as well, gaining the same 83 efficiency. Therefore, a protocol based on sockets will work at 84 least as well as one based on file descriptors, with the added 85 benefit of being more portable. 86 87New Types 88 89 None 90 91New Functions 92 93 None 94 95New Tokens for EGL_NV_stream_socket 96 97 Accepted by eglCreateStreamKHR and returned by eglQueryStreamKHR 98 when attribute is EGL_STREAM_PROTOCOL_NV: 99 100 EGL_STREAM_PROTOCOL_SOCKET_NV 0x324B 101 102 Accepted as attribute names by eglCreateStreamKHR and 103 eglQueryStreamKHR functions 104 105 EGL_SOCKET_HANDLE_NV 0x324C 106 EGL_SOCKET_TYPE_NV 0x324D 107 108New Tokens for EGL_NV_stream_socket_unix 109 110 Accepted by eglCreateStreamKHR and returned by eglQueryStreamKHR 111 when attribute is EGL_SOCKET_TYPE_NV: 112 113 EGL_SOCKET_TYPE_UNIX_NV 0x324E 114 115New Tokens for EGL_NV_stream_socket_inet 116 117 Accepted by eglCreateStreamKHR and returned by eglQueryStreamKHR 118 when attribute is EGL_SOCKET_TYPE_NV: 119 120 EGL_SOCKET_TYPE_INET_NV 0x324F 121 122Add to list of failures in section "3.10.1 Creating an EGLStream" in EGL_KHR stream: 123 124 - EGL_BAD_MATCH is generated if the value of EGL_STREAM_PROTOCOL_NV 125 is EGL_STREAM_PROTOCOL_SOCKET_NV and values are not provided for 126 EGL_SOCKET_HANDLE_NV and EGL_SOCKET_TYPE_NV. 127 128Add to "Table 3.10.4.4 EGLStream Attributes" in EGL_KHR_stream: 129 130 Attribute Read/Write Type Section 131 -------------------------- ---------- ------ ---------- 132 EGL_SOCKET_HANDLE_NV io EGLint 3.10.4.y 133 EGL_SOCKET_TYPE_NV io EGLint 3.10.4.y+1 134 135In section "3.10.4.x+1 EGL_STREAM_PROTOCOL_NV Attribute" of 136EGL_NV_stream_remote, add EGL_STREAM_PROTOCOL_SOCKET_NV to the list of 137legal values and add 138 139 A value of EGL_STREAM_PROTOCOL_SOCKET_NV indicates that the stream 140 is a remote stream whose communication is established using a socket 141 connection provided by the application. The details of the messages 142 passed through the socket are implementation dependent, and may be 143 influenced by the stream and socket types. This value for the 144 EGL_STREAM_PROTOCOL_NV attribute is compatible with values of 145 EGL_STREAM_CROSS_OBJECT_NV, EGL_STREAM_CROSS_DISPLAY_NV, 146 EGL_STREAM_CROSS_PROCESS_NV, and EGL_STREAM_CROSS_PARTITION_NV for 147 the EGL_STREAM_TYPE_NV attribute. 148 149Add new subsections to the end of section "3.10.4 EGLStream Attributes" 150in EGL_KHR_stream: 151 152 3.10.4.y EGL_SOCKET_HANDLE_NV Attribute 153 154 The EGL_SOCKET_HANDLE_NV attribute may be set when the stream 155 is created, and provides the handle to a blocking socket which will 156 be used to communicate with the other endpoint of the stream. If the 157 value of EGL_STREAM_PROTOCOL_NV is not EGL_STREAM_PROTOCOL_SOCKET_NV, 158 this attribute is ignored. 159 160 The type of this value is operating system dependent, and the 161 default value will be an invalid socket handle for the operating 162 system. In particular, for unix-like operating systems, the value is 163 a socket file descriptor as returned by socket() and related 164 functions, and the default value is -1. 165 166 Prior to creating the EGLStream object, the application may use the 167 socket handle as it wishes. But once the EGLStream object has been 168 successfully created, it assumes full ownership of this socket. If 169 the application subsequently writes to, reads from, or closes the 170 socket, undefined behavior will result. Furthermore, if any data 171 sent over the socket prior to creating the EGLStream object is not 172 consumed before the opposite EGLStream object is created, undefined 173 behavior will result. 174 175 When the EGLStream object is deleted, the socket handle will be 176 closed by the stream. 177 178 3.10.4.y+1 EGL_SOCKET_TYPE_NV Attribute 179 180 The EGL_SOCKET_TYPE_NV attribute may be set when the stream is 181 created, and indicates the type of the socket provided by the 182 EGL_STREAM_SOCKET_HANDLE_NV attribute. If the value of 183 EGL_STREAM_PROTOCOL_NV is not EGL_STREAM_PROTOCOL_SOCKET_NV this 184 attribute is ignored. 185 186 The default value is EGL_NONE. 187 188If EGL_NV_stream_socket_unix is present, add to section "3.10.4.y+1 189EGL_SOCKET_TYPE_NV Attribute" above: 190 191 A value of EGL_SOCKET_TYPE_UNIX_NV indicates that the socket handle 192 represents a Unix domain socket, created with SOCK_STREAM type. 193 194If EGL_NV_stream_socket_inet is present, add to section "3.10.4.y+1 195EGL_SOCKET_TYPE_NV Attribute" above: 196 197 A value of EGL_SOCKET_TYPE_INET_NV indicates that the socket handle 198 represents an internet protocol socket, created with SOCK_STREAM 199 type. 200 201Issues 202 203 None 204 205Revision History 206 207 #6 (October 27, 2016) Daniel Kartch 208 - Indicate that the socket handle provided should represent 209 a blocking socket. 210 211 #5 (June 7, 2016) Daniel Kartch 212 - Add contact and clean up in preparation for publication. 213 214 #4 (September 16, 2015) Zander Clucas 215 - Indicated STREAM_SOCKET_PROTOCOL as compatible with socket 216 type CROSS_PROCESS. 217 218 #3 (December 16, 2014) Daniel Kartch 219 - Refined overview to clarify comparison with 220 EGL_KHR_cross_process_fd. 221 - Indicated SOCK_STREAM as a requirement for the socket types. 222 223 #2 (December 11, 2014) Daniel Kartch 224 - Rewrote as NV draft for earlier release. 225 - Reserved enum values. 226 227 #1 (October 10, 2014) Daniel Kartch 228 - Initial EXT draft 229 230