Name
+eglCreatePbufferSurface — + create a new EGL pixel buffer surface +
+C Specification
+
+ EGLSurface eglCreatePbufferSurface(
+ |
+ EGLDisplay display, | +
| + | EGLConfig config, | +
| + | EGLint 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. +
+
+ -
+
+
+
attrib_list+ + +
+ -
+
+ Specifies pixel buffer surface attributes. + May be
+NULLor empty + (first attribute isEGL_NONE). +
+
Description
+
+ eglCreatePbufferSurface creates an
+ off-screen pixel buffer surface and returns its handle. If
+ eglCreatePbufferSurface fails to create
+ a pixel buffer surface, EGL_NO_SURFACE
+ is returned.
+
+ 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 ofGL_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 ofGL_LINEAR. The default + value ofEGL_GL_COLORSPACEis +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_HEIGHT+ +
+ -
+
+ Specifies the required height of the pixel buffer + surface. The default value is +
+0. +
+ -
+
+
EGL_LARGEST_PBUFFER+ +
+ -
+
+ Requests the largest available pixel buffer surface + when the allocation would otherwise fail. Use + eglQuerySurface + to retrieve the dimensions of the allocated pixel + buffer. The default value is +
+EGL_FALSE. +
+ -
+
+
EGL_MIPMAP_TEXTURE+ +
+ -
+
+ Specifies whether storage for mipmaps should be + allocated. Space for mipmaps will be set aside if + the attribute value is
+EGL_TRUE+ andEGL_TEXTURE_FORMATis not +EGL_NO_TEXTURE. The default + value isEGL_FALSE. +
+ -
+
+
EGL_TEXTURE_FORMAT+ +
+ -
+
+ Specifies the format of the texture that will be + created when a pbuffer is bound to a texture map. + Possible values are +
+EGL_NO_TEXTURE, +EGL_TEXTURE_RGB, and +EGL_TEXTURE_RGBA. The default + value isEGL_NO_TEXTURE. +
+ -
+
+
EGL_TEXTURE_TARGET+ +
+ -
+
+ Specifies the target for the texture that will be + created when the pbuffer is created with a texture + format of
+EGL_TEXTURE_RGBor +EGL_TEXTURE_RGBA. Possible + values areEGL_NO_TEXTURE, or +EGL_TEXTURE_2D. The default + value isEGL_NO_TEXTURE. +
+ -
+
+
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 + isEGL_VG_ALPHA_FORMAT_PRE, + then alpha values are premultiplied. The default + value ofEGL_VG_ALPHA_FORMATis +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_COLORSPACEis +EGL_VG_COLORSPACE_sRGB. +
+ -
+
+
EGL_WIDTH+ +
+ -
+
+ Specifies the required width of the pixel buffer + surface. The default value is +
+0. +
+
+ 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 dimensions of the allocated pixel buffer
+ surface or the ID of config.
+
+ Use eglDestroySurface + to destroy the surface. +
+Notes
+
+ Attribute EGL_GL_COLORSPACE, and the
+ EGL_OPENGL_ES3_BIT bit value for attribute
+ EGL_RENDERABLE_TYPE, are supported only if
+ the EGL version is 1.5 or greater.
+
+ Attributes
+ EGL_RENDERABLE_TYPE,
+ 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.
+
+ If the value of config attribute
+ EGL_TEXTURE_FORMAT is not
+ EGL_NO_TEXTURE, then the pbuffer width
+ and height specify the size of the level zero texture image
+
+ If EGL_LARGEST_PBUFFER is specified and
+ if the pbuffer will be used as a texture (i.e. the value of
+ EGL_TEXTURE_TARGET is
+ EGL_TEXTURE_2D, and the value of
+ EGL_TEXTURE FORMAT is
+ EGL_TEXTURE_RGB or
+ EGL_TEXTURE_RGBA), then the aspect
+ ratio will be preserved and the new width and height will be
+ valid sizes for the texture target (e.g. if the underlying
+ OpenGL ES implementation does not support non-power-of-two
+ textures, both the width and height will be a power of 2).
+
+ The contents of the depth and stencil buffers may not be + preserved when rendering a texture to the pbuffer and + switching which image of the texture is rendered to (e.g., + switching from rendering one mipmap level to rendering + another). +
+Errors
+
+ EGL_NO_SURFACE is returned if creation of
+ the context 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 an EGL frame buffer configuration.
+
+ EGL_BAD_ATTRIBUTE is generated if
+ attrib_list contains an invalid pixel
+ buffer attribute or if an attribute value is not recognized
+ or out of range.
+
+ EGL_BAD_ATTRIBUTE is generated if
+ attrib_list contains any of the
+ attributes EGL_MIPMAP_TEXTURE,
+ EGL_TEXTURE_FORMAT, or
+ EGL_TEXTURE_TARGET, and
+ config does not support OpenGL ES
+ rendering (e.g. the EGL version is 1.2 or later, and the
+ EGL_RENDERABLE_TYPE attribute of
+ config does not include at least one
+ of EGL_OPENGL_ES_BIT,
+ EGL_OPENGL_ES2_BIT, or
+ EGL_OPENGL_ES3_BIT),
+
+ EGL_BAD_ALLOC is generated if there are not
+ enough resources to allocate the new surface.
+
+ EGL_BAD_MATCH is generated if
+ config does not support rendering to pixel buffers
+ (the EGL_SURFACE_TYPE attribute does not contain
+ EGL_PBUFFER_BIT).
+
+ EGL_BAD_MATCH is generated if the
+ EGL_TEXTURE_FORMAT attribute is not
+ EGL_NO_TEXTURE, and
+ EGL_WIDTH and/or
+ EGL_HEIGHT specify an invalid size
+ (e.g., the texture size is not a power of 2, and the
+ underlying OpenGL ES implementation does not support
+ non-power-of-two textures).
+
+ EGL_BAD_MATCH is generated if
+ the EGL_TEXTURE_FORMAT attribute is
+ EGL_NO_TEXTURE, and
+ EGL_TEXTURE_TARGET is something other
+ than EGL_NO_TEXTURE; or,
+ EGL_TEXTURE_FORMAT is something other
+ than EGL_NO_TEXTURE, and
+ EGL_TEXTURE_TARGET is
+ EGL_NO_TEXTURE.
+
+ 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).
+
See Also
++ eglDestroySurface, + eglChooseConfig, + eglGetConfigs, + eglMakeCurrent, + eglQuerySurface +
++
+
+ + Copyright © 2003-2014 The Khronos Group Inc. + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and/or associated documentation files (the + "Materials"), to deal in the Materials without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Materials, and to + permit persons to whom the Materials are furnished to do so, subject to + the condition that this copyright notice and permission notice shall be included + in all copies or substantial portions of the Materials. +
++
+