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