Name
KHR_stream_cross_process_fd
Name Strings
EGL_KHR_stream_cross_process_fd
Contributors
Acorn Pooley
Ian Stewart
Contacts
Acorn Pooley, NVIDIA (apooley 'at' nvidia.com)
Notice
Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the EGL Working Group on June 6, 2012.
Approved by the Khronos Board of Promoters on July 27, 2012.
Version
Version 8 - June 5, 2012
Number
EGL Extension #41
Dependencies
Requires EGL 1.2.
Requires EGL_KHR_stream
This extension is written based on the wording of the EGL 1.2
specification.
This extension interacts with the following extensions if they are
also present:
EGL_KHR_stream_producer_eglsurface
EGL_KHR_stream_consumer_gltexture
EGL_KHR_stream_producer_aldatalocator
EGL_KHR_stream_fifo
Overview
This extension allows an EGLStreamKHR object handle to be
duplicated into another process so that the EGLStream producer can
be in one process while the EGLStream consumer can be in another
process.
Duplicating the EGLStreamKHR object handle into another process is
peformed in 3 steps
1) Get a file descriptor associated with the EGLStream.
2) Duplicate the file descriptor into another process.
3) Create an EGLStreamKHR from the duplicated file descriptor in
the other process.
The file descriptor is obtained by calling
eglGetStreamFileDescriptorKHR().
Duplicating the file descriptor into another process is outside
the scope of this extension. See issue #1 for an example of how
to do this on a Linux system.
The EGLStreamKHR object handle is created in the second process by
passing the file descriptor to the
eglCreateStreamFromFileDescriptorKHR() function. This must be
done while the EGLStream is in the EGL_STREAM_STATE_CREATED_KHR
state.
Once the EGLStreamKHR object handle is created in the second
process, it refers to the same EGLStream as the EGLStreamKHR
object handle in the original process. A consumer can be
associated with the EGLStream from either process. A producer can
be associated with the EGLStream from either process.
New Types
Represents a native OS file descriptor.
typedef int EGLNativeFileDescriptorKHR
New Procedures and Functions
EGLNativeFileDescriptorKHR eglGetStreamFileDescriptorKHR(
EGLDisplay dpy,
EGLStreamKHR stream);
EGLStreamKHR eglCreateStreamFromFileDescriptorKHR(
EGLDisplay dpy,
EGLNativeFileDescriptorKHR file_descriptor);
New Tokens
Returned from eglGetStreamFileDescriptorKHR on error.
#define EGL_NO_FILE_DESCRIPTOR_KHR ((EGLNativeFileDescriptorKHR)(-1))
Add a new section just after section "3.10.1 Creating an EGLStream" in
the EGL_KHR_stream extension
3.10.1.1 Duplicating an EGLStream from a file descriptor
Call
EGLNativeFileDescriptorKHR eglGetStreamFileDescriptorKHR(
EGLDisplay dpy,
EGLStreamKHR stream);
to create a file descriptor that refers to the EGLStream.
<stream> must be an EGLStream in the EGL_STREAM_STATE_CREATED_KHR
state. eglGetStreamFileDescriptorKHR may be called at most once
for any <stream>.
On success a file descriptor is returned which can be used
to create a duplicate EGLStreamKHR handle which refers to the same
underlying EGLStream as <stream>. This file descriptor and file
descriptors duplicated from it should only be used in a call to
eglCreateStreamFromFileDescriptorKHR() and/or a call to close().
In particular reads, writes, and other operations on the file
descriptor result in undefined behavior.
On failure the functions returns EGL_NO_FILE_DESCRIPTOR_KHR and
generates an error
- EGL_BAD_DISPLAY is generated if <dpy> is not a valid
initialized EGLDisplay
- EGL_BAD_STREAM_KHR is generated if <stream> is not a valid
EGLStreamKHR handle created for <dpy>.
- EGL_BAD_STATE_KHR is generated if <stream> is not in the
EGL_STREAM_STATE_CREATED_KHR state or if
eglGetStreamFileDescriptorKHR() has previously been called
on this <stream>.
- EGL_BAD_STATE_KHR is generated if <stream> was not created
by eglCreateStreamKHR (e.g. if it was created by
eglCreateStreamFromFileDescriptorKHR).
The file descriptor returned by eglGetStreamFileDescriptorKHR can
be duplicated into a different process address space using system
specific mechanisms outside the scope of this specification. (For
example, on a Linux system it can be sent over a UNIX domain
socket using sendmsg/recvmsg.)
Call
EGLStreamKHR eglCreateStreamFromFileDescriptorKHR(
EGLDisplay dpy,
EGLNativeFileDescriptorKHR file_descriptor);
to create an EGLStreamKHR handle. <file_descriptor> must be a
file descriptor returned by eglGetStreamFileDescriptorKHR or a
file descriptor duplicated from such a file descriptor (possibly
in a different process). The EGLStream must be in the
EGL_STREAM_STATE_CREATED_KHR or EGL_STREAM_STATE_CONNECTING_KHR
state.
On success an EGLStreamKHR handle is returned. This EGLStreamKHR
handle refers to the same EGLStream which was used to create the
<file_descriptor> or the file descriptor from which
<file_descriptor> was duplicated.
After the file descriptor is passed to
eglCreateStreamFromFileDescriptorKHR it may no longer be used to
create a new EGLStream.
On failure EGL_NO_STREAM_KHR is returned and an error is
generated.
- EGL_BAD_DISPLAY is generated if <dpy> is not a valid
initialized EGLDisplay
- EGL_BAD_ATTRIBUTE is generated if <file_descriptor> is
EGL_NO_FILE_DESCRIPTOR_KHR.
- EGL_BAD_ATTRIBUTE is generated if <file_descriptor> is
not an open file descriptor referring to an EGLStream
created on the same Native Display as <dpy>.
- EGL_BAD_ATTRIBUTE is generated if <file_descriptor> has
already been used to create a stream handle via a previous
call to eglCreateStreamFromFileDescriptorKHR.
- EGL_BAD_STATE_KHR is generated if <stream> is not in the
EGL_STREAM_STATE_CREATED_KHR or
EGL_STREAM_STATE_CONNECTING_KHR state.
The application should close the file descriptor and any file
descriptors duplicated from it once
eglCreateStreamFromFileDescriptorKHR has returned. Open file
descriptors will consume resources until they are closed or until
all processes that hold them open have terminated. Closing the
file descriptors after calling
eglCreateStreamFromFileDescriptorKHR will not affect the
associated EGLStream. If an application calls
eglGetStreamFileDescriptorKHR and then determines that the file
descriptor and/or the EGLStream is no longer needed then it may
(and should) close the file descriptor and destroy the EGLStream
(this is not considered an error).
If a process which has successfully connected a consumer or
producer to the EGLStream terminates (normally or abnormally) then
the EGLStream state becomes EGL_STREAM_STATE_DISCONNECTED_KHR.
If a process has created an EGLStreamKHR handle either with
eglCreateStreamKHR or eglCreateStreamFromFileDescriptorKHR but has
not connected a producer or consumer to the stream, and this
process terminates (normally or abnormally) then this has no
effect on the EGLStream.
Interactions with the EGL_KHR_stream_producer_eglsurface extension.
The eglCreateStreamProducerSurfaceKHR() function can be called
from either the process that created the original EGLStreamKHR, or
from the process which called eglCreateStreamFromFileDescriptorKHR.
Interactions with the EGL_KHR_stream_consumer_gltexture extension.
The eglStreamConsumerGLTextureExternalKHR() function can be called
from either the process that created the original EGLStreamKHR, or
from the process which called
eglCreateStreamFromFileDescriptorKHR. The
eglStreamConsumerAcquireKHR() and eglStreamConsumerReleaseKHR()
functions must be called from the same process that calls
eglStreamConsumerGLTextureExternalKHR() (or else they will fail
and generate an EGL_BAD_ACCESS error).
Interactions with the EGL_KHR_stream_producer_aldatalocator extension.
The CreateMediaPlayer() method can be called from either the
process that created the original EGLStreamKHR, or from the
process which called eglCreateStreamFromFileDescriptorKHR.
Interactions with the EGL_KHR_stream_fifo extension.
The queries for EGL_STREAM_FIFO_LENGTH_KHR,
EGL_STREAM_TIME_NOW_KHR, EGL_STREAM_TIME_CONSUMER_KHR, and
EGL_STREAM_TIME_PRODUCER_KHR can be made from either process. The
time values returned by the EGL_STREAM_TIME_NOW_KHR query will be
consistent between the two processes (i.e. if queried at the same
time from both processes, the same value (plus or minus some
margin of error) will be returned).
Interactions with the EGL_NV_stream_cross_process_fd extension.
These extensions may both exist on the same implementation and
are functionally equivalent. Mixing and matching file descriptors
from one extension with functions from the other is allowed.
Interactions with the EGL_NV_stream_sync extension.
The eglCreateStreamSyncNV() function may only be called from a
process which has successfully connected a consumer to the
EGLStream. Otherwise eglCreateStreamSyncNV generates a
EGL_BAD_ACCESS error.
Issues
1. How does the application transfer the file descriptor to
another process?
RESOLVED: This is outside the scope of this extension. The
application can use existing operating system mechanisms for
duplicating the file descriptor into another process. For
example on Linux a file descriptor can be sent over a UNIX
domain socket using the following code (call send_fd() to
send the file descriptor, and receive_fd() in the other
process to receive the file descriptor). (The following code
is placed into the public domain by its author, Acorn Pooley)
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/un.h>
#define FATAL_ERROR() exit(1)
#define SOCKET_NAME "/tmp/example_socket"
/* Send <fd_to_send> (a file descriptor) to another process */
/* over a unix domain socket named <socket_name>. */
/* <socket_name> can be any nonexistant filename. */
void send_fd(const char *socket_name, int fd_to_send)
{
int sock_fd;
struct sockaddr_un sock_addr;
struct msghdr msg;
struct iovec iov[1];
char ctrl_buf[CMSG_SPACE(sizeof(int))];
struct cmsghdr *cmsg = NULL;
sock_fd = socket(PF_UNIX, SOCK_STREAM, 0);
if (sock_fd < 0) FATAL_ERROR();
memset(&sock_addr, 0, sizeof(struct sockaddr_un));
sock_addr.sun_family = AF_UNIX;
strncpy(sock_addr.sun_path,
socket_name,
sizeof(sock_addr.sun_path)-1);
while (connect(sock_fd,
(const struct sockaddr*)&sock_addr,
sizeof(struct sockaddr_un))) {
printf("Waiting for reciever\n");
sleep(1);
}
memset(&msg, 0, sizeof(msg));
iov[0].iov_len = 1; // must send at least 1 byte
iov[0].iov_base = "x"; // any byte value (value ignored)
msg.msg_iov = iov;
msg.msg_iovlen = 1;
memset(ctrl_buf, 0, sizeof(ctrl_buf));
msg.msg_control = ctrl_buf;
msg.msg_controllen = sizeof(ctrl_buf);
cmsg = CMSG_FIRSTHDR(&msg);
cmsg->cmsg_level = SOL_SOCKET;
cmsg->cmsg_type = SCM_RIGHTS;
cmsg->cmsg_len = CMSG_LEN(sizeof(int));
*((int *) CMSG_DATA(cmsg)) = fd_to_send;
msg.msg_controllen = cmsg->cmsg_len;
if (sendmsg(sock_fd, &msg, 0) <= 0) FATAL_ERROR();
close(sock_fd);
}
/* Listen on a unix domain socket named <socket_name> and */
/* receive a file descriptor from another process. */
/* Returns the file descriptor. Note: the integer value */
/* of the file descriptor may be different from the */
/* integer value in the other process, but the file */
/* descriptors in each process will refer to the same file */
/* object in the kernel. */
int receive_fd(const char *socket_name)
{
int listen_fd;
struct sockaddr_un sock_addr;
int connect_fd;
struct sockaddr_un connect_addr;
socklen_t connect_addr_len = 0;
struct msghdr msg;
struct iovec iov[1];
char msg_buf[1];
char ctrl_buf[CMSG_SPACE(sizeof(int))];
struct cmsghdr *cmsg;
listen_fd = socket(PF_UNIX, SOCK_STREAM, 0);
if (listen_fd < 0) FATAL_ERROR();
unlink(socket_name);
memset(&sock_addr, 0, sizeof(struct sockaddr_un));
sock_addr.sun_family = AF_UNIX;
strncpy(sock_addr.sun_path,
socket_name,
sizeof(sock_addr.sun_path)-1);
if (bind(listen_fd,
(const struct sockaddr*)&sock_addr,
sizeof(struct sockaddr_un)))
FATAL_ERROR();
if (listen(listen_fd, 1)) FATAL_ERROR();
connect_fd = accept(
listen_fd,
(struct sockaddr *)&connect_addr,
&connect_addr_len);
close(listen_fd);
unlink(socket_name);
if (connect_fd < 0) FATAL_ERROR();
memset(&msg, 0, sizeof(msg));
iov[0].iov_base = msg_buf;
iov[0].iov_len = sizeof(msg_buf);
msg.msg_iov = iov;
msg.msg_iovlen = 1;
msg.msg_control = ctrl_buf;
msg.msg_controllen = sizeof(ctrl_buf);
if (recvmsg(connect_fd, &msg, 0) <= 0) FATAL_ERROR();
cmsg = CMSG_FIRSTHDR(&msg);
if (!cmsg) FATAL_ERROR();
if (cmsg->cmsg_level != SOL_SOCKET) FATAL_ERROR();
if (cmsg->cmsg_type != SCM_RIGHTS) FATAL_ERROR();
return *(int *) CMSG_DATA(cmsg);
}
2. Does this extension work with all consumers and all producers?
RESOLVED: This extension is compatible with
EGL_KHR_stream_producer_eglsurface
EGL_KHR_stream_consumer_gltexture
EGL_KHR_stream_producer_aldatalocator
EGL_KHR_stream_fifo
as described in the Interactions sections. Whether an
EGLStream that has been duplicated into another process will
work with other types of consumers and producers should be
mentioned in the description of those consumers and producers.
3. Does EGL create a file descriptor for every EGLStream when the
EGLStream is created, or is the file descriptor be created
when eglGetStreamFileDescriptorKHR is called?
RESOLVED: This is implementation dependent. However,
recommended behavior is to create the file descriptor when
eglGetStreamFileDescriptorKHR is called. This avoids
polluting the file descriptor namespace (which may have a
limited size on some systems) with descriptors for EGLStreams
which will only be used inside a single process. The
eglGetStreamFileDescriptorKHR function will fail and generate
an EGL_BAD_ALLOC error if it is unable to allocate a file
descriptor for the EGLStream.
4. Should the EGLStream be created from the file descriptor with
the existing eglCreateStreamKHR function or with a new
function dedicated to that purpose?
The advantage of creating a new function is that a new
parameter can be added with a specific type. This is not
really necessary for this extension since a file descriptor is
a small integer which can fit into the EGLint in the
eglCreateStreamKHR attrib_list. However, other similar
extensions may be invented that use other types of handles
(not file descriptors) which may not fit into an EGLint.
Creating a dedicated function allows these other extensions to
use a similar function.
RESOLVED: Use a different function.
5. How does this extension interact with the
EGL_NV_stream_cross_process_fd extension?
RESOLVED: These extensions may both exist on the same
implementation and are functionally equivalent. Mixing and
matching file descriptors from one extension with functions
from the other is allowed.
6. Who should close the file descriptors and when?
There is no way for the EGL implementation to safely close all
the file descriptors associated with an EGLStream because some
of them may have been created using OS specific duping
mechanisms. Also, the app may need to close a descriptor if
it runs into an error before it is able to call
eglCreateStreamFromFileDescriptorKHR. Therefore the
application will need to close at least some of the created
file descriptors. To make things simple and clear it is
therefore left up to the app to close all the file
descriptors. The app is not *required* to do this, but not
doing so will "leak" file descriptors which will consume
resources until the process terminates.
Allowing the app to close all file descriptors as soon as
eglCreateStreamFromFileDescriptorKHR returns simplifies the
app (no need to keep track of open file descriptors).
RESOLVED: Application is responsible for closing all file
descriptors. They can be safely closed as soon as
eglCreateStreamFromFileDescriptorKHR returns.
7. What happens when an invalid file descriptor is passed to
eglCreateStreamFromFileDescriptorKHR()?
RESOLVED: The implementation must detect this and generate an
error. If the file descriptor refers to a file then the
implementation may not modify the file, change the seek
location, or otherwise modify the file descriptor.
8. What happens if one process hangs or crashes?
RESOLVED: If either the consumer's or producer's process
terminates (normally or abnormally) the EGL implementation
must notice this and place the EGLStream in
EGL_STREAM_STATE_DISCONNECTED_KHR state. If the consumer is
blocked in a eglStreamConsumerAcquireKHR() call, the call will
generate an EGL_BAD_STATE_KHR message and return EGL_FALSE.
If the consumer process has created a reusable sync object with
eglCreateStreamSyncNV() and is blocking in a
eglClientWaitSyncKHR() call, the call will block until the
timeout runs out.
If the producer process "hangs" (e.g. enters an infinite loop,
blocks in a kernel call, etc) then the consumer process will
continue to function. The consumer will continue to use the
last frame that the producer produced. If the producer has
not yet produced a frame then the EGLStream will be in
EGL_STREAM_STATE_EMPTY_KHR state and no frame will be
available. The consumer process can block in some situations:
- If a EGL_CONSUMER_ACQUIRE_TIMEOUT_USEC_KHR is set then
eglStreamConsumerAcquireKHR() will block until the
timeout runs out (or indefinitely if timeout is
negative).
- eglClientWaitSyncKHR() will block until the timeout runs
out.
If the consumer process "hangs" then the producer process will
continue to function. If the EGLStream has had
EGL_STREAM_FIFO_LENGTH_KHR set to a nonzero value then the
producer will block indefinitely when it fills the fifo and
tries to insert another frame. Otherwise the producer will
not block (as new frames are inserted into the EGLStream old
ones will be discarded).
Revision History
#8 (June 5, 2012) Acorn Pooley
- rename from XXX to KHR
#7 (June 5, 2012) Acorn Pooley
- Add issue 8.
- Better define EGLStream behavior when a process terminates.
- Add Interactions with the EGL_NV_stream_sync extension.
#6 (April 20, 2012) Ian Stewart
- Fix extension/function names in interactions
- Removed references to NV_stream_sync.
- Changed interactions with NV_stream_cross_process_fd such
that they are interchangeable.
#5 (April 18, 2012) Acorn Pooley
- Add issue 7
- define errors generated when passing invalid file descriptors
#4 (January 29, 2012) Acorn Pooley
- Fork EGL_XXX_stream_cross_process_fd.txt from
EGL_NV_stream_cross_process_fd.txt to make changes suggested
by working group.
- add issues 4, 5, and 6.
#3 (January 6, 2012) Acorn Pooley
- fix typos (EGLImage -> EGLStream)
#2 (December 7, 2011) Acorn Pooley
- Upload to Khronos for review
#1 (September 27, 2011) Acorn Pooley
- Initial draft
# vim:ai:ts=4:sts=4:expandtab:textwidth=70