eglCreatePlatformWindowSurface - EGL Reference Pages

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). +