Name

eglCreatePlatformWindowSurface — create a new EGL on-screen rendering surface

C Specification

EGLSurface eglCreatePlatformWindowSurface( EGLDisplay display,
  EGLConfig config,
  void * native_window,
  EGLAttrib const * attrib_list);
 

Parameters

display

Specifies the EGL display connection.

config

Specifies the EGL frame buffer configuration that defines the frame buffer resource available to the surface.

native_window

Specifies the native window.

attrib_list

Specifies a list of attributes for the window surface. May be NULL or empty (first attribute is EGL_NONE).

Description

eglCreatePlatformWindowSurface creates an on-screen EGL window surface and returns a handle to it. Any EGL context created with a compatible EGLConfig can be used to render into this surface.

If eglCreatePlatformWindowSurface fails to create a window surface, EGL_NO_SURFACE is returned.

native_window must belong to the same platform as display, and EGL considers the returned EGLSurface as belonging to that same platform. The EGL extension that defines the platform to which display belongs also defines the requirements for the native_window parameter.

Surface attributes are specified as a list of attribute-value pairs, terminated with EGL_NONE. Accepted attributes are:

EGL_GL_COLORSPACE

Specifies the color space used by OpenGL and OpenGL ES when rendering to the surface. If its value is EGL_GL_COLORSPACE_SRGB, then a non-linear, perceptually uniform color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB. If its value is EGL_GL_COLORSPACE_LINEAR, then a linear color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR. The default value of EGL_GL_COLORSPACE is EGL_GL_COLORSPACE_LINEAR.

Note that the EGL_GL_COLORSPACE attribute is used only by OpenGL and OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not distinguish multiple colorspace models. Refer to the ``sRGB Conversion'' sections of the OpenGL 4.6 and OpenGL ES 3.2 Specifications for more information.

EGL_RENDER_BUFFER

Specifies which buffer should be used for client API rendering to the window. If its value is EGL_SINGLE_BUFFER, then client APIs should render directly into the visible window. If its value is EGL_BACK_BUFFER, then client APIs should render into the back buffer. The default value of EGL_RENDER_BUFFER is EGL_BACK_BUFFER.

Client APIs may not be able to respect the requested rendering buffer. To determine the actual buffer being rendered to by a context, call eglQueryContext.

EGL_VG_ALPHA_FORMAT

Specifies how alpha values are interpreted by OpenVG when rendering to the surface. If its value is EGL_VG_ALPHA_FORMAT_NONPRE, then alpha values are not premultipled. If its value is EGL_VG_ALPHA_FORMAT_PRE, then alpha values are premultiplied. The default value of EGL_VG_ALPHA_FORMAT is EGL_VG_ALPHA_FORMAT_NONPRE.

EGL_VG_COLORSPACE

Specifies the color space used by OpenVG when rendering to the surface. If its value is EGL_VG_COLORSPACE_sRGB, then a non-linear, perceptually uniform color space is assumed, with a corresponding VGImageFormat of form VG_s*. If its value is EGL_VG_COLORSPACE_LINEAR, then a linear color space is assumed, with a corresponding VGImageFormat of form VG_l*. The default value of EGL_VG_COLORSPACE is EGL_VG_COLORSPACE_sRGB.

Any EGL rendering context that was created with respect to config can be used to render into the surface. Use eglMakeCurrent to attach an EGL rendering context to the surface.

Use eglQuerySurface to retrieve the ID of config.

Use eglDestroySurface to destroy the surface.

Notes

Attribute EGL_GL_COLORSPACE is supported only if the EGL version is 1.5 or greater.

Attributes EGL_RENDER_BUFFER, EGL_VG_ALPHA_FORMAT, and EGL_VG_COLORSPACE, and the corresponding attribute values, are supported only if the EGL version is 1.2 or greater.

The EGL_VG_ALPHA_FORMAT and EGL_VG_COLORSPACE attributes are used only by OpenVG and EGL itself. Refer to section 11.2 of the OpenVG 1.0 specification for more information. The platform's use and interpretation of alpha values is outside the scope of EGL. However, the preferred behavior is for platforms to ignore the value of EGL_VG_ALPHA_FORMAT when compositing window surfaces.

Errors

If display and native_window do not belong to the same platform, then undefined behavior occurs.

EGL_NO_SURFACE is returned if creation of the surface fails.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONFIG is generated if config is not a valid EGL frame buffer configuration.

EGL_BAD_NATIVE_WINDOW may be generated if native_window is not a valid native window for the same platform as display.

EGL_BAD_ATTRIBUTE is generated if attrib_list contains an invalid window attribute or if an attribute value is not recognized or is out of range.

EGL_BAD_ALLOC is generated if there is already an EGLSurface associated with native_window (as a result of a previous eglCreatePlatformWindowSurface call).

EGL_BAD_ALLOC is generated if the implementation cannot allocate resources for the new EGL window.

EGL_BAD_MATCH is generated if the pixel format of native_window does not correspond to the format, type, and size of the color buffers required by config. EGL_BAD_MATCH is generated if the pixel

EGL_BAD_MATCH is generated if config does not support rendering to windows (the EGL_SURFACE_TYPE attribute does not contain EGL_WINDOW_BIT).

EGL_BAD_MATCH is generated if config does not support the specified OpenVG alpha format attribute (the value of EGL_VG_ALPHA_FORMAT is EGL_VG_ALPHA_FORMAT_PRE and the EGL_VG_ALPHA_FORMAT_PRE_BIT is not set in the EGL_SURFACE_TYPE attribute of config) or colorspace attribute (the value of EGL_VG_COLORSPACE is EGL_VG_COLORSPACE_LINEAR and the EGL_VG_COLORSPACE_LINEAR_IT is not set in the EGL_SURFACE_TYPE attribute of config).