| Name |
| |
| EXT_platform_x11 |
| |
| Name Strings |
| |
| EGL_EXT_platform_x11 |
| |
| Contributors |
| |
| Chad Versace <chad.versace@intel.com> |
| James Jones <jajones@nvidia.com> |
| |
| Contacts |
| |
| Chad Versace <chad.versace@intel.com> |
| |
| Status |
| |
| Complete |
| |
| Version |
| |
| Version 13, 2014-03-10 |
| |
| Number |
| |
| EGL Extension #59 |
| |
| Extension Type |
| |
| EGL client extension |
| |
| Dependencies |
| |
| Requires EGL_EXT_client_extensions to query its existence without |
| a display. |
| |
| Requires EGL_EXT_platform_base. |
| |
| This extension is written against the wording of version 7 of the |
| EGL_EXT_platform_base specification. |
| |
| Overview |
| |
| This extension defines how to create EGL resources from native X11 |
| resources using the functions defined by EGL_EXT_platform_base. |
| |
| This extension defines only how to create EGL resources from Xlib |
| resources. It does not define how to do so from xcb resources. All X11 |
| types discussed here are defined by the header `Xlib.h`. |
| |
| New Types |
| |
| None |
| |
| New Procedures and Functions |
| |
| None |
| |
| New Tokens |
| |
| Accepted as the <platform> argument of eglGetPlatformDisplayEXT: |
| |
| EGL_PLATFORM_X11_EXT 0x31D5 |
| |
| Accepted as an attribute name in the <attrib_list> argument of |
| eglGetPlatformDisplayEXT: |
| |
| EGL_PLATFORM_X11_SCREEN_EXT 0x31D6 |
| |
| Additions to the EGL Specification |
| |
| None. |
| |
| New Behavior |
| |
| To determine if the EGL implementation supports this extension, clients |
| should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY. |
| |
| On the X11 platform, an EGLDisplay refers to a specific X11 screen rather |
| than an X11 display connection. This is the case because separate X11 |
| screens, even when belonging to the same X11 display connection, may |
| reside on different GPUs and/or be driven by different drivers. Therefore, |
| different X11 screens may have different EGL capabilities. |
| |
| To obtain an EGLDisplay backed by an X11 screen, call |
| eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_X11_EXT. The |
| <native_display> parameter specifies the X11 display connection to use, and |
| must point to a valid X11 `Display` or be NULL. If <native_display> is |
| EGL_DEFAULT_DISPLAY, then EGL will create [1] a connection to the default |
| X11 display. The environment variable DISPLAY determines the default X11 |
| display as described in the manual page for XOpenDisplay(3). The value of |
| attribute EGL_PLATFORM_X11_SCREEN_EXT specifies the X11 screen to use. If |
| the attribute is omitted from <attrib_list>, then the display connection's |
| default screen is used. Otherwise, the attribute's value must be a valid |
| screen on the display connection. If the attribute's value is not a valid |
| screen, then an EGL_BAD_ATTRIBUTE error is generated. |
| |
| [fn1] The method by which EGL creates a connection to the default X11 |
| display is an internal implementation detail. The implementation may use |
| XOpenDisplay, xcb_connect, or any other method. |
| |
| To obtain an on-screen rendering surface from an X11 Window, call |
| eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and |
| a <native_window> that points to an X11 Window. |
| |
| To obtain an offscreen rendering surface from an X11 Pixmap, call |
| eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and |
| a <native_pixmap> that points to an X11 Pixmap. |
| |
| Issues |
| |
| 1. Should this extension permit EGL_DEFAULT_DISPLAY as input to |
| eglGetPlatformDisplayEXT()? |
| |
| RESOLVED. Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT |
| returns an EGLDisplay backed by the default X11 display. |
| |
| 2. When given EGL_DEFAULT_DISPLAY, does eglGetPlatformDisplayEXT reuse an |
| existing X11 display connection or create a new one? |
| |
| RESOLVED. eglGetPlatformDisplayEXT creates a new connection because the |
| alternative is infeasible. EGL cannot reliably detect if the client |
| process already has a X11 display connection. |
| |
| |
| Example Code |
| |
| // This example program creates two EGL surfaces: one from an X11 Window |
| // and the other from an X11 Pixmap. |
| // |
| // If the macro USE_EGL_EXT_PLATFORM_X11 is defined, then the program |
| // creates the surfaces using the methods defined in this specification. |
| // Otherwise, it uses the methods defined by the EGL 1.4 specification. |
| // |
| // Compile with `cc -std=c99 example.c -lX11 -lEGL`. |
| |
| #include <stdlib.h> |
| #include <string.h> |
| |
| #include <EGL/egl.h> |
| #include <X11/Xlib.h> |
| |
| struct my_display { |
| Display *x11; |
| EGLDisplay egl; |
| }; |
| |
| struct my_config { |
| struct my_display dpy; |
| XVisualInfo *x11; |
| Colormap colormap; |
| EGLConfig egl; |
| }; |
| |
| struct my_window { |
| struct my_config config; |
| Window x11; |
| EGLSurface egl; |
| }; |
| |
| struct my_pixmap { |
| struct my_config config; |
| Pixmap x11; |
| EGLSurface egl; |
| }; |
| |
| static void |
| check_extensions(void) |
| { |
| #ifdef USE_EGL_EXT_PLATFORM_X11 |
| const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS); |
| |
| if (!client_extensions) { |
| // EGL_EXT_client_extensions is unsupported. |
| abort(); |
| } |
| if (!strstr(client_extensions, "EGL_EXT_platform_x11")) { |
| abort(); |
| } |
| #endif |
| } |
| |
| static struct my_display |
| get_display(void) |
| { |
| struct my_display dpy; |
| |
| dpy.x11 = XOpenDisplay(NULL); |
| if (!dpy.x11) { |
| abort(); |
| } |
| |
| #ifdef USE_EGL_EXT_PLATFORM_X11 |
| dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_X11_EXT, dpy.x11, |
| NULL); |
| #else |
| dpy.egl = eglGetDisplay(dpy.x11); |
| #endif |
| |
| if (dpy.egl == EGL_NO_DISPLAY) { |
| abort(); |
| } |
| |
| EGLint major, minor; |
| if (!eglInitialize(dpy.egl, &major, &minor)) { |
| abort(); |
| } |
| |
| return dpy; |
| } |
| |
| static struct my_config |
| get_config(struct my_display dpy) |
| { |
| struct my_config config = { |
| .dpy = dpy, |
| }; |
| |
| EGLint egl_config_attribs[] = { |
| EGL_BUFFER_SIZE, 32, |
| EGL_RED_SIZE, 8, |
| EGL_GREEN_SIZE, 8, |
| EGL_BLUE_SIZE, 8, |
| EGL_ALPHA_SIZE, 8, |
| |
| EGL_DEPTH_SIZE, EGL_DONT_CARE, |
| EGL_STENCIL_SIZE, EGL_DONT_CARE, |
| |
| EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, |
| EGL_SURFACE_TYPE, EGL_WINDOW_BIT | EGL_PIXMAP_BIT, |
| EGL_NONE, |
| }; |
| |
| EGLint num_configs; |
| if (!eglChooseConfig(dpy.egl, |
| egl_config_attribs, |
| &config.egl, 1, |
| &num_configs)) { |
| abort(); |
| } |
| if (num_configs == 0) { |
| abort(); |
| } |
| |
| XVisualInfo x11_visual_info_template; |
| if (!eglGetConfigAttrib(dpy.egl, |
| config.egl, |
| EGL_NATIVE_VISUAL_ID, |
| (EGLint*) &x11_visual_info_template.visualid)) { |
| abort(); |
| } |
| |
| int num_visuals; |
| config.x11 = XGetVisualInfo(dpy.x11, |
| VisualIDMask, |
| &x11_visual_info_template, |
| &num_visuals); |
| if (!config.x11) { |
| abort(); |
| } |
| |
| config.colormap = XCreateColormap(dpy.x11, |
| RootWindow(dpy.x11, 0), |
| config.x11->visual, |
| AllocNone); |
| if (config.colormap == None) { |
| abort(); |
| } |
| |
| return config; |
| } |
| |
| static struct my_window |
| get_window(struct my_config config) |
| { |
| XSetWindowAttributes attr; |
| unsigned long mask; |
| |
| struct my_window window = { |
| .config = config, |
| }; |
| |
| attr.colormap = config.colormap; |
| mask = CWColormap; |
| |
| window.x11 = XCreateWindow(config.dpy.x11, |
| DefaultRootWindow(config.dpy.x11), // parent |
| 0, 0, // x, y |
| 256, 256, // width, height |
| 0, // border_width |
| config.x11->depth, |
| InputOutput, // class |
| config.x11->visual, |
| mask, // valuemask |
| &attr); // attributes |
| if (!window.x11) { |
| abort(); |
| } |
| |
| #ifdef USE_EGL_EXT_PLATFORM_X11 |
| window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl, |
| config.egl, |
| &window.x11, |
| NULL); |
| #else |
| window.egl = eglCreateWindowSurface(config.dpy.egl, |
| config.egl, |
| window.x11, |
| NULL); |
| #endif |
| |
| if (window.egl == EGL_NO_SURFACE) { |
| abort(); |
| } |
| |
| return window; |
| } |
| |
| static struct my_pixmap |
| get_pixmap(struct my_config config) |
| { |
| struct my_pixmap pixmap = { |
| .config = config, |
| }; |
| |
| pixmap.x11 = XCreatePixmap(config.dpy.x11, |
| DefaultRootWindow(config.dpy.x11), |
| 256, 256, // width, height |
| config.x11->depth); |
| if (!pixmap.x11) { |
| abort(); |
| } |
| |
| #ifdef USE_EGL_EXT_PLATFORM_X11 |
| pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl, |
| config.egl, |
| &pixmap.x11, |
| NULL); |
| #else |
| pixmap.egl = eglCreatePixmapSurface(config.dpy.egl, |
| config.egl, |
| pixmap.x11, |
| NULL); |
| #endif |
| |
| if (pixmap.egl == EGL_NO_SURFACE) { |
| abort(); |
| } |
| |
| return pixmap; |
| } |
| |
| int |
| main(void) |
| { |
| check_extensions(); |
| |
| struct my_display dpy = get_display(); |
| struct my_config config = get_config(dpy); |
| struct my_window window = get_window(config); |
| struct my_pixmap pixmap = get_pixmap(config); |
| |
| return 0; |
| } |
| |
| Revision History |
| |
| Version 13, 2014-03-10 (Chad Versace) |
| - Update text to reflect resolution of issue #1. State that |
| <native_display> may be EGL_DEFAULT_DISPLAY. |
| - Explain in more detail how EGL connects to the default X11 display. |
| - Add and resolve issue #2. |
| |
| Version 12, 2014-02-11 (Chad Versace) |
| - Fix 2nd argument to XCreatePixmap in example code. |
| |
| Version 11, 2013-07-10 (Jon Leech) |
| - Fix enumerant values and assign extension number for publication |
| (Bug 10240). |
| |
| Version 10, 2013-07-03 (Chad Versace) |
| - Add "Extension Type" section, required by EGL_EXT_client_extensions v9. |
| |
| Version 9, 2013-06-11 (Chad Versace) |
| - Replace reference to version 5 of EGL_EXT_platform_base to version 7. |
| - Add James Jones as contributor. |
| |
| Version 8, 2013-06-07 (Chad Versace) |
| - Assign enum values to new tokens. |
| |
| Version 7, 2013-06-07 (Chad Versace) |
| - Explicitly require EGL_EXT_client_extensions in the Dependencies |
| section. |
| |
| Version 6, 2013-06-07 (Chad Versace) |
| - Add attribute EGL_PLATFORM_X11_SCREEN_EXT. |
| |
| Version 5, 2013-06-07 (Chad Versace) |
| - Rephrase against version 7 of EGL_EXT_platform_base. |
| |
| Version 4, 2013-06-07 (Chad Versace) |
| - Fix compilation of example code. |
| |
| Version 3, 2013-04-26 (Chad Versace) |
| - Add missing EXT suffix to new token. |
| |
| Version 2, 2013-04-22 (Chad Versace) |
| - Discuss EGL_DEFAULT_DISPLAY. |
| - Fix minor typographical and grammatical errors. |
| |
| Version 1, 2013.03.24 (Chad Versace) |
| - First draft |