| <refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreatePbufferSurface"> |
| <info> |
| <copyright> |
| <year>2003-2014</year> |
| <holder>The Khronos Group Inc.</holder> |
| </copyright> |
| </info> |
| <refmeta> |
| <refentrytitle>eglCreatePbufferSurface</refentrytitle> |
| <manvolnum>3G</manvolnum> |
| </refmeta> |
| <refnamediv> |
| <refname>eglCreatePbufferSurface</refname> |
| <refpurpose> |
| create a new <acronym>EGL</acronym> pixel buffer surface |
| </refpurpose> |
| </refnamediv> |
| <refsynopsisdiv> |
| <title>C Specification</title> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>EGLSurface <function>eglCreatePbufferSurface</function></funcdef> |
| <paramdef>EGLDisplay <parameter>display</parameter></paramdef> |
| <paramdef>EGLConfig <parameter>config</parameter></paramdef> |
| <paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| </refsynopsisdiv> |
| <refsect1 xml:id="parameters"><title>Parameters</title> |
| <variablelist> |
| <varlistentry> |
| <term><parameter>display</parameter></term> |
| <listitem><para>Specifies the EGL display connection.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>config</parameter></term> |
| <listitem><para> |
| Specifies the EGL frame buffer configuration that defines the |
| frame buffer resource available to the surface. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>attrib_list</parameter></term> |
| <listitem><para> |
| Specifies pixel buffer surface attributes. |
| May be <constant>NULL</constant> or empty |
| (first attribute is <constant>EGL_NONE</constant>). |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| <refsect1 xml:id="description"><title>Description</title> |
| <para> |
| <function>eglCreatePbufferSurface</function> creates an |
| off-screen pixel buffer surface and returns its handle. If |
| <function>eglCreatePbufferSurface</function> fails to create |
| a pixel buffer surface, <constant>EGL_NO_SURFACE</constant> |
| is returned. |
| </para> |
| <para> |
| Surface attributes are specified as a list of |
| attribute-value pairs, terminated with |
| <constant>EGL_NONE</constant>. Accepted attributes |
| are: |
| </para> |
| <variablelist> |
| <varlistentry> |
| <term><constant>EGL_GL_COLORSPACE</constant></term> |
| <listitem> |
| <para> |
| Specifies the color space used by OpenGL and OpenGL ES |
| when rendering to the surface. If its value is |
| <constant>EGL_GL_COLORSPACE_SRGB</constant>, then a |
| non-linear, perceptually uniform color space is assumed, |
| with a corresponding |
| <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant> |
| value of <constant>GL_SRGB</constant>. If its value is |
| <constant>EGL_GL_COLORSPACE_LINEAR</constant>, then a |
| linear color space is assumed, with a corresponding |
| <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant> |
| value of <constant>GL_LINEAR</constant>. The default |
| value of <constant>EGL_GL_COLORSPACE</constant> is |
| <constant>EGL_GL_COLORSPACE_SRGB</constant>. |
| </para> |
| <para> |
| Note that the <constant>EGL_GL_COLORSPACE</constant> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_HEIGHT</constant></term> |
| <listitem> |
| <para> |
| Specifies the required height of the pixel buffer |
| surface. The default value is |
| <constant>0</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_LARGEST_PBUFFER</constant></term> |
| <listitem> |
| <para> |
| Requests the largest available pixel buffer surface |
| when the allocation would otherwise fail. Use |
| <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> |
| to retrieve the dimensions of the allocated pixel |
| buffer. The default value is |
| <constant>EGL_FALSE</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_MIPMAP_TEXTURE</constant></term> |
| <listitem> |
| <para> |
| Specifies whether storage for mipmaps should be |
| allocated. Space for mipmaps will be set aside if |
| the attribute value is <constant>EGL_TRUE</constant> |
| and <constant>EGL_TEXTURE_FORMAT</constant> is not |
| <constant>EGL_NO_TEXTURE</constant>. The default |
| value is <constant>EGL_FALSE</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_TEXTURE_FORMAT</constant></term> |
| <listitem> |
| <para> |
| Specifies the format of the texture that will be |
| created when a pbuffer is bound to a texture map. |
| Possible values are |
| <constant>EGL_NO_TEXTURE</constant>, |
| <constant>EGL_TEXTURE_RGB</constant>, and |
| <constant>EGL_TEXTURE_RGBA</constant>. The default |
| value is <constant>EGL_NO_TEXTURE</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_TEXTURE_TARGET</constant></term> |
| <listitem> |
| <para> |
| Specifies the target for the texture that will be |
| created when the pbuffer is created with a texture |
| format of <constant>EGL_TEXTURE_RGB</constant> or |
| <constant>EGL_TEXTURE_RGBA</constant>. Possible |
| values are <constant>EGL_NO_TEXTURE</constant>, or |
| <constant>EGL_TEXTURE_2D</constant>. The default |
| value is <constant>EGL_NO_TEXTURE</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_VG_ALPHA_FORMAT</constant></term> |
| <listitem> |
| <para> |
| Specifies how alpha values are interpreted by OpenVG |
| when rendering to the surface. If its value is |
| <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>, |
| then alpha values are not premultipled. If its value |
| is <constant>EGL_VG_ALPHA_FORMAT_PRE</constant>, |
| then alpha values are premultiplied. The default |
| value of <constant>EGL_VG_ALPHA_FORMAT</constant> is |
| <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_VG_COLORSPACE</constant></term> |
| <listitem> |
| <para> |
| Specifies the color space used by OpenVG when |
| rendering to the surface. If its value is |
| <constant>EGL_VG_COLORSPACE_sRGB</constant>, then a |
| non-linear, perceptually uniform color space is |
| assumed, with a corresponding |
| <type>VGImageFormat</type> of form |
| <constant>VG_s*</constant>. If its value is |
| <constant>EGL_VG_COLORSPACE_LINEAR</constant>, then |
| a linear color space is assumed, with a |
| corresponding <type>VGImageFormat</type> of form |
| <constant>VG_l*</constant>. The default value of |
| <constant>EGL_VG_COLORSPACE</constant> is |
| <constant>EGL_VG_COLORSPACE_sRGB</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><constant>EGL_WIDTH</constant></term> |
| <listitem> |
| <para> |
| Specifies the required width of the pixel buffer |
| surface. The default value is |
| <constant>0</constant>. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para> |
| Any EGL rendering context that was created with respect to |
| <parameter>config</parameter> can be used to render into the |
| surface. Use |
| <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> |
| to attach an EGL rendering context to the surface. |
| </para> |
| <para> |
| Use |
| <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> |
| to retrieve the dimensions of the allocated pixel buffer |
| surface or the ID of <parameter>config</parameter>. |
| </para> |
| <para> |
| Use <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry> |
| to destroy the surface. |
| </para> |
| </refsect1> |
| <refsect1 xml:id="notes"><title>Notes</title> |
| <para> |
| Attribute <constant>EGL_GL_COLORSPACE</constant>, and the |
| <constant>EGL_OPENGL_ES3_BIT</constant> bit value for attribute |
| <constant>EGL_RENDERABLE_TYPE</constant>, are supported only if |
| the EGL version is 1.5 or greater. |
| </para> |
| <para> |
| Attributes |
| <constant>EGL_RENDERABLE_TYPE</constant>, |
| <constant>EGL_VG_ALPHA_FORMAT</constant>, and |
| <constant>EGL_VG_COLORSPACE</constant>, and the |
| corresponding attribute values, are supported only if the |
| EGL version is 1.2 or greater. |
| </para> |
| <para> |
| If the value of <parameter>config</parameter> attribute |
| <constant>EGL_TEXTURE_FORMAT</constant> is not |
| <constant>EGL_NO_TEXTURE</constant>, then the pbuffer width |
| and height specify the size of the level zero texture image |
| </para> |
| <para> |
| If <constant>EGL_LARGEST_PBUFFER</constant> is specified and |
| if the pbuffer will be used as a texture (i.e. the value of |
| <constant>EGL_TEXTURE_TARGET</constant> is |
| <constant>EGL_TEXTURE_2D</constant>, and the value of |
| <constant>EGL_TEXTURE FORMAT</constant> is |
| <constant>EGL_TEXTURE_RGB</constant> or |
| <constant>EGL_TEXTURE_RGBA</constant>), 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). |
| </para> |
| <para> |
| 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). |
| </para> |
| </refsect1> |
| <refsect1 xml:id="errors"><title>Errors</title> |
| <para> |
| <constant>EGL_NO_SURFACE</constant> is returned if creation of |
| the context fails. |
| </para> |
| <para> |
| <constant>EGL_BAD_DISPLAY</constant> is generated if |
| <parameter>display</parameter> is not an EGL display connection. |
| </para> |
| <para> |
| <constant>EGL_NOT_INITIALIZED</constant> is generated if |
| <parameter>display</parameter> has not been initialized. |
| </para> |
| <para> |
| <constant>EGL_BAD_CONFIG</constant> is generated if |
| <parameter>config</parameter> is not an EGL frame buffer configuration. |
| </para> |
| <para> |
| <constant>EGL_BAD_ATTRIBUTE</constant> is generated if |
| <parameter>attrib_list</parameter> contains an invalid pixel |
| buffer attribute or if an attribute value is not recognized |
| or out of range. |
| </para> |
| <para> |
| <constant>EGL_BAD_ATTRIBUTE</constant> is generated if |
| <parameter>attrib_list</parameter> contains any of the |
| attributes <constant>EGL_MIPMAP_TEXTURE</constant>, |
| <constant>EGL_TEXTURE_FORMAT</constant>, or |
| <constant>EGL_TEXTURE_TARGET</constant>, and |
| <parameter>config</parameter> does not support OpenGL ES |
| rendering (e.g. the EGL version is 1.2 or later, and the |
| <constant>EGL_RENDERABLE_TYPE</constant> attribute of |
| <parameter>config</parameter> does not include at least one |
| of <constant>EGL_OPENGL_ES_BIT</constant>, |
| <constant>EGL_OPENGL_ES2_BIT</constant>), or |
| <constant>EGL_OPENGL_ES3_BIT</constant>), |
| </para> |
| <para> |
| <constant>EGL_BAD_ALLOC</constant> is generated if there are not |
| enough resources to allocate the new surface. |
| </para> |
| <para> |
| <constant>EGL_BAD_MATCH</constant> is generated if |
| <parameter>config</parameter> does not support rendering to pixel buffers |
| (the <constant>EGL_SURFACE_TYPE</constant> attribute does not contain |
| <constant>EGL_PBUFFER_BIT</constant>). |
| </para> |
| <para> |
| <constant>EGL_BAD_MATCH</constant> is generated if the |
| <constant>EGL_TEXTURE_FORMAT</constant> attribute is not |
| <constant>EGL_NO_TEXTURE</constant>, and |
| <constant>EGL_WIDTH</constant> and/or |
| <constant>EGL_HEIGHT</constant> 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). |
| </para> |
| <para> |
| <constant>EGL_BAD_MATCH</constant> is generated if |
| the <constant>EGL_TEXTURE_FORMAT</constant> attribute is |
| <constant>EGL_NO_TEXTURE</constant>, and |
| <constant>EGL_TEXTURE_TARGET</constant> is something other |
| than <constant>EGL_NO_TEXTURE</constant>; or, |
| <constant>EGL_TEXTURE_FORMAT</constant> is something other |
| than <constant>EGL_NO_TEXTURE</constant>, and |
| <constant>EGL_TEXTURE_TARGET</constant> is |
| <constant>EGL_NO_TEXTURE</constant>. |
| </para> |
| <para> |
| <constant>EGL_BAD_MATCH</constant> is generated if |
| <parameter>config</parameter> does not support the specified |
| OpenVG alpha format attribute (the value of |
| <constant>EGL_VG_ALPHA_FORMAT</constant> is |
| <constant>EGL_VG_ALPHA_FORMAT_PRE</constant> and the |
| <constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant> is not set |
| in the <constant>EGL_SURFACE_TYPE</constant> attribute of |
| <parameter>config</parameter>) or colorspace attribute (the |
| value of <constant>EGL_VG_COLORSPACE</constant> is |
| <constant>EGL_VG_COLORSPACE_LINEAR</constant> and the |
| <constant>EGL_VG_COLORSPACE_LINEAR_IT</constant> is not set |
| in the <constant>EGL_SURFACE_TYPE</constant> attribute of |
| <parameter>config</parameter>). |
| </para> |
| </refsect1> |
| <refsect1 xml:id="seealso"><title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> |
| </para> |
| </refsect1> |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> |
| </refentry> |