1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" 3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> 4<refentry xml:base="" id="eglCreatePbufferSurface"> 5 <refentryinfo> 6 <copyright> 7 <year>2003-2014</year> 8 <holder>The Khronos Group Inc.</holder> 9 </copyright> 10 </refentryinfo> 11 <refmeta> 12 <refentrytitle>eglCreatePbufferSurface</refentrytitle> 13 <manvolnum>3G</manvolnum> 14 </refmeta> 15 <refnamediv> 16 <refname>eglCreatePbufferSurface</refname> 17 <refpurpose> 18 create a new <acronym>EGL</acronym> pixel buffer surface 19 </refpurpose> 20 </refnamediv> 21 <refsynopsisdiv> 22 <title>C Specification</title> 23 <funcsynopsis> 24 <funcprototype> 25 <funcdef>EGLSurface <function>eglCreatePbufferSurface</function></funcdef> 26 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 27 <paramdef>EGLConfig <parameter>config</parameter></paramdef> 28 <paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef> 29 </funcprototype> 30 </funcsynopsis> 31 </refsynopsisdiv> 32 <refsect1 id="parameters"><title>Parameters</title> 33 <variablelist> 34 <varlistentry> 35 <term><parameter>display</parameter></term> 36 <listitem><para>Specifies the EGL display connection.</para></listitem> 37 </varlistentry> 38 <varlistentry> 39 <term><parameter>config</parameter></term> 40 <listitem><para> 41 Specifies the EGL frame buffer configuration that defines the 42 frame buffer resource available to the surface. 43 </para></listitem> 44 </varlistentry> 45 <varlistentry> 46 <term><parameter>attrib_list</parameter></term> 47 <listitem><para> 48 Specifies pixel buffer surface attributes. 49 May be <constant>NULL</constant> or empty 50 (first attribute is <constant>EGL_NONE</constant>). 51 </para></listitem> 52 </varlistentry> 53 </variablelist> 54 </refsect1> 55 <refsect1 id="description"><title>Description</title> 56 <para> 57 <function>eglCreatePbufferSurface</function> creates an 58 off-screen pixel buffer surface and returns its handle. If 59 <function>eglCreatePbufferSurface</function> fails to create 60 a pixel buffer surface, <constant>EGL_NO_SURFACE</constant> 61 is returned. 62 </para> 63 <para> 64 Surface attributes are specified as a list of 65 attribute-value pairs, terminated with 66 <constant>EGL_NONE</constant>. Accepted attributes 67 are: 68 </para> 69 <variablelist> 70 <varlistentry> 71 <term><constant>EGL_HEIGHT</constant></term> 72 <listitem> 73 <para> 74 Specifies the required height of the pixel buffer 75 surface. The default value is 76 <constant>0</constant>. 77 </para> 78 </listitem> 79 </varlistentry> 80 <varlistentry> 81 <term><constant>EGL_LARGEST_PBUFFER</constant></term> 82 <listitem> 83 <para> 84 Requests the largest available pixel buffer surface 85 when the allocation would otherwise fail. Use 86 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 87 to retrieve the dimensions of the allocated pixel 88 buffer. The default value is 89 <constant>EGL_FALSE</constant>. 90 </para> 91 </listitem> 92 </varlistentry> 93 <varlistentry> 94 <term><constant>EGL_MIPMAP_TEXTURE</constant></term> 95 <listitem> 96 <para> 97 Specifies whether storage for mipmaps should be 98 allocated. Space for mipmaps will be set aside if 99 the attribute value is <constant>EGL_TRUE</constant> 100 and <constant>EGL_TEXTURE_FORMAT</constant> is not 101 <constant>EGL_NO_TEXTURE</constant>. The default 102 value is <constant>EGL_FALSE</constant>. 103 </para> 104 </listitem> 105 </varlistentry> 106 <varlistentry> 107 <term><constant>EGL_TEXTURE_FORMAT</constant></term> 108 <listitem> 109 <para> 110 Specifies the format of the texture that will be 111 created when a pbuffer is bound to a texture map. 112 Possible values are 113 <constant>EGL_NO_TEXTURE</constant>, 114 <constant>EGL_TEXTURE_RGB</constant>, and 115 <constant>EGL_TEXTURE_RGBA</constant>. The default 116 value is <constant>EGL_NO_TEXTURE</constant>. 117 </para> 118 </listitem> 119 </varlistentry> 120 <varlistentry> 121 <term><constant>EGL_TEXTURE_TARGET</constant></term> 122 <listitem> 123 <para> 124 Specifies the target for the texture that will be 125 created when the pbuffer is created with a texture 126 format of <constant>EGL_TEXTURE_RGB</constant> or 127 <constant>EGL_TEXTURE_RGBA</constant>. Possible 128 values are <constant>EGL_NO_TEXTURE</constant>, or 129 <constant>EGL_TEXTURE_2D</constant>. The default 130 value is <constant>EGL_NO_TEXTURE</constant>. 131 </para> 132 </listitem> 133 </varlistentry> 134 <varlistentry> 135 <term><constant>EGL_VG_ALPHA_FORMAT</constant></term> 136 <listitem> 137 <para> 138 Specifies how alpha values are interpreted by OpenVG 139 when rendering to the surface. If its value is 140 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>, 141 then alpha values are not premultipled. If its value 142 is <constant>EGL_VG_ALPHA_FORMAT_PRE</constant>, 143 then alpha values are premultiplied. The default 144 value of <constant>EGL_VG_ALPHA_FORMAT</constant> is 145 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>. 146 </para> 147 </listitem> 148 </varlistentry> 149 <varlistentry> 150 <term><constant>EGL_VG_COLORSPACE</constant></term> 151 <listitem> 152 <para> 153 Specifies the color space used by OpenVG when 154 rendering to the surface. If its value is 155 <constant>EGL_VG_COLORSPACE_sRGB</constant>, then a 156 non-linear, perceptually uniform color space is 157 assumed, with a corresponding 158 <type>VGImageFormat</type> of form 159 <constant>VG_s*</constant>. If its value is 160 <constant>EGL_VG_COLORSPACE_LINEAR</constant>, then 161 a linear color space is assumed, with a 162 corresponding <type>VGImageFormat</type> of form 163 <constant>VG_l*</constant>. The default value of 164 <constant>EGL_VG_COLORSPACE</constant> is 165 <constant>EGL_VG_COLORSPACE_sRGB</constant>. 166 </para> 167 </listitem> 168 </varlistentry> 169 <varlistentry> 170 <term><constant>EGL_WIDTH</constant></term> 171 <listitem> 172 <para> 173 Specifies the required width of the pixel buffer 174 surface. The default value is 175 <constant>0</constant>. 176 </para> 177 </listitem> 178 </varlistentry> 179 </variablelist> 180 <para> 181 Any EGL rendering context that was created with respect to 182 <parameter>config</parameter> can be used to render into the 183 surface. Use 184 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> 185 to attach an EGL rendering context to the surface. 186 </para> 187 <para> 188 Use 189 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 190 to retrieve the dimensions of the allocated pixel buffer 191 surface or the ID of <parameter>config</parameter>. 192 </para> 193 <para> 194 Use <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry> 195 to destroy the surface. 196 </para> 197 </refsect1> 198 <refsect1 id="notes"><title>Notes</title> 199 <para> 200 Attributes 201 <constant>EGL_RENDERABLE_TYPE</constant>, 202 <constant>EGL_VG_ALPHA_FORMAT</constant>, and 203 <constant>EGL_VG_COLORSPACE</constant>, and the 204 corresponding attribute values, are supported only if the 205 EGL version is 1.2 or greater. 206 </para> 207 <para> 208 If the value of <parameter>config</parameter> attribute 209 <constant>EGL_TEXTURE_FORMAT</constant> is not 210 <constant>EGL_NO_TEXTURE</constant>, then the pbuffer width 211 and height specify the size of the level zero texture image 212 </para> 213 <para> 214 If <constant>EGL_LARGEST_PBUFFER</constant> is specified and 215 if the pbuffer will be used as a texture (i.e. the value of 216 <constant>EGL_TEXTURE_TARGET</constant> is 217 <constant>EGL_TEXTURE_2D</constant>, and the value of 218 <constant>EGL_TEXTURE FORMAT</constant> is 219 <constant>EGL_TEXTURE_RGB</constant> or 220 <constant>EGL_TEXTURE_RGBA</constant>), then the aspect 221 ratio will be preserved and the new width and height will be 222 valid sizes for the texture target (e.g. if the underlying 223 OpenGL ES implementation does not support non-power-of-two 224 textures, both the width and height will be a power of 2). 225 </para> 226 <para> 227 The contents of the depth and stencil buffers may not be 228 preserved when rendering a texture to the pbuffer and 229 switching which image of the texture is rendered to (e.g., 230 switching from rendering one mipmap level to rendering 231 another). 232 </para> 233 </refsect1> 234 <refsect1 id="errors"><title>Errors</title> 235 <para> 236 <constant>EGL_NO_SURFACE</constant> is returned if creation of 237 the context fails. 238 </para> 239 <para> 240 <constant>EGL_BAD_DISPLAY</constant> is generated if 241 <parameter>display</parameter> is not an EGL display connection. 242 </para> 243 <para> 244 <constant>EGL_NOT_INITIALIZED</constant> is generated if 245 <parameter>display</parameter> has not been initialized. 246 </para> 247 <para> 248 <constant>EGL_BAD_CONFIG</constant> is generated if 249 <parameter>config</parameter> is not an EGL frame buffer configuration. 250 </para> 251 <para> 252 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 253 <parameter>attrib_list</parameter> contains an invalid pixel 254 buffer attribute or if an attribute value is not recognized 255 or out of range. 256 </para> 257 <para> 258 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 259 <parameter>attrib_list</parameter> contains any of the 260 attributes <constant>EGL_MIPMAP_TEXTURE</constant>, 261 <constant>EGL_TEXTURE_FORMAT</constant>, or 262 <constant>EGL_TEXTURE_TARGET</constant>, and 263 <parameter>config</parameter> does not support OpenGL ES 264 rendering (e.g. the EGL version is 1.2 or later, and the 265 <constant>EGL_RENDERABLE_TYPE</constant> attribute of 266 <parameter>config</parameter> does not include at least one 267 of <constant>EGL_OPENGL_ES_BIT</constant> or 268 <constant>EGL_OPENGL_ES2_BIT</constant>). 269 </para> 270 <para> 271 <constant>EGL_BAD_ALLOC</constant> is generated if there are not 272 enough resources to allocate the new surface. 273 </para> 274 <para> 275 <constant>EGL_BAD_MATCH</constant> is generated if 276 <parameter>config</parameter> does not support rendering to pixel buffers 277 (the <constant>EGL_SURFACE_TYPE</constant> attribute does not contain 278 <constant>EGL_PBUFFER_BIT</constant>). 279 </para> 280 <para> 281 <constant>EGL_BAD_MATCH</constant> is generated if the 282 <constant>EGL_TEXTURE_FORMAT</constant> attribute is not 283 <constant>EGL_NO_TEXTURE</constant>, and 284 <constant>EGL_WIDTH</constant> and/or 285 <constant>EGL_HEIGHT</constant> specify an invalid size 286 (e.g., the texture size is not a power of 2, and the 287 underlying OpenGL ES implementation does not support 288 non-power-of-two textures). 289 </para> 290 <para> 291 <constant>EGL_BAD_MATCH</constant> is generated if 292 the <constant>EGL_TEXTURE_FORMAT</constant> attribute is 293 <constant>EGL_NO_TEXTURE</constant>, and 294 <constant>EGL_TEXTURE_TARGET</constant> is something other 295 than <constant>EGL_NO_TEXTURE</constant>; or, 296 <constant>EGL_TEXTURE_FORMAT</constant> is something other 297 than <constant>EGL_NO_TEXTURE</constant>, and 298 <constant>EGL_TEXTURE_TARGET</constant> is 299 <constant>EGL_NO_TEXTURE</constant>. 300 </para> 301 <para> 302 <constant>EGL_BAD_MATCH</constant> is generated if 303 <parameter>config</parameter> does not support the specified 304 OpenVG alpha format attribute (the value of 305 <constant>EGL_VG_ALPHA_FORMAT</constant> is 306 <constant>EGL_VG_ALPHA_FORMAT_PRE</constant> and the 307 <constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant> is not set 308 in the <constant>EGL_SURFACE_TYPE</constant> attribute of 309 <parameter>config</parameter>) or colorspace attribute (the 310 value of <constant>EGL_VG_COLORSPACE</constant> is 311 <constant>EGL_VG_COLORSPACE_LINEAR</constant> and the 312 <constant>EGL_VG_COLORSPACE_LINEAR_IT</constant> is not set 313 in the <constant>EGL_SURFACE_TYPE</constant> attribute of 314 <parameter>config</parameter>). 315 </para> 316 </refsect1> 317 <refsect1 id="seealso"><title>See Also</title> 318 <para> 319 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>, 320 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>, 321 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, 322 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>, 323 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 324 </para> 325 </refsect1> 326 <refsect3 id="Copyright"><title></title> 327 <!-- Content included from copyright.inc.xsl --> 328 <imageobject> 329 <imagedata fileref="KhronosLogo.jpg" format="jpg" /> 330 </imageobject> 331 <para /> 332 </refsect3> 333</refentry> 334
