mirror of
https://github.com/openharmony/third_party_egl.git
synced 2026-07-19 17:14:29 -04:00
stonesxd
360 lines
17 KiB
XML
Executable File
360 lines
17 KiB
XML
Executable File
<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_LINEAR</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>
|