1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreatePbufferSurface - EGL Reference Pages</title> 5 <link rel="stylesheet" type="text/css" href="khronos-man.css"/> 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.2"/> 7 </head> 8 <body> 9 <header/> 10 <div class="refentry" id="eglCreatePbufferSurface"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglCreatePbufferSurface — 15 create a new <abbr class="acronym">EGL</abbr> pixel buffer surface 16 </p> 17 </div> 18 <div class="refsynopsisdiv"> 19 <h2>C Specification</h2> 20 <div class="funcsynopsis"> 21 <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> 22 <tr> 23 <td> 24 <code class="funcdef">EGLSurface <strong class="fsfunc">eglCreatePbufferSurface</strong>(</code> 25 </td> 26 <td>EGLDisplay <var class="pdparam">display</var>, </td> 27 </tr> 28 <tr> 29 <td> </td> 30 <td>EGLConfig <var class="pdparam">config</var>, </td> 31 </tr> 32 <tr> 33 <td> </td> 34 <td>EGLint const * <var class="pdparam">attrib_list</var><code>)</code>;</td> 35 </tr> 36 </table> 37 <div class="funcprototype-spacer"> </div> 38 </div> 39 </div> 40 <div class="refsect1" id="parameters"> 41 <h2>Parameters</h2> 42 <div class="variablelist"> 43 <dl class="variablelist"> 44 <dt> 45 <span class="term"> 46 <em class="parameter"> 47 <code>display</code> 48 </em> 49 </span> 50 </dt> 51 <dd> 52 <p>Specifies the EGL display connection.</p> 53 </dd> 54 <dt> 55 <span class="term"> 56 <em class="parameter"> 57 <code>config</code> 58 </em> 59 </span> 60 </dt> 61 <dd> 62 <p> 63 Specifies the EGL frame buffer configuration that defines the 64 frame buffer resource available to the surface. 65 </p> 66 </dd> 67 <dt> 68 <span class="term"> 69 <em class="parameter"> 70 <code>attrib_list</code> 71 </em> 72 </span> 73 </dt> 74 <dd> 75 <p> 76 Specifies pixel buffer surface attributes. 77 May be <code class="constant">NULL</code> or empty 78 (first attribute is <code class="constant">EGL_NONE</code>). 79 </p> 80 </dd> 81 </dl> 82 </div> 83 </div> 84 <div class="refsect1" id="description"> 85 <h2>Description</h2> 86 <p> 87 <code class="function">eglCreatePbufferSurface</code> creates an 88 off-screen pixel buffer surface and returns its handle. If 89 <code class="function">eglCreatePbufferSurface</code> fails to create 90 a pixel buffer surface, <code class="constant">EGL_NO_SURFACE</code> 91 is returned. 92 </p> 93 <p> 94 Surface attributes are specified as a list of 95 attribute-value pairs, terminated with 96 <code class="constant">EGL_NONE</code>. Accepted attributes 97 are: 98 </p> 99 <div class="variablelist"> 100 <dl class="variablelist"> 101 <dt> 102 <span class="term"> 103 <code class="constant">EGL_GL_COLORSPACE</code> 104 </span> 105 </dt> 106 <dd> 107 <p> 108 Specifies the color space used by OpenGL and OpenGL ES 109 when rendering to the surface. If its value is 110 <code class="constant">EGL_GL_COLORSPACE_SRGB</code>, then a 111 non-linear, perceptually uniform color space is assumed, 112 with a corresponding 113 <code class="constant">GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</code> 114 value of <code class="constant">GL_SRGB</code>. If its value is 115 <code class="constant">EGL_GL_COLORSPACE_LINEAR</code>, then a 116 linear color space is assumed, with a corresponding 117 <code class="constant">GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</code> 118 value of <code class="constant">GL_LINEAR</code>. The default 119 value of <code class="constant">EGL_GL_COLORSPACE</code> is 120 <code class="constant">EGL_GL_COLORSPACE_LINEAR</code>. 121 </p> 122 <p> 123 Note that the <code class="constant">EGL_GL_COLORSPACE</code> 124 attribute is used only by OpenGL and OpenGL ES contexts 125 supporting sRGB framebuffers. EGL itself does not 126 distinguish multiple colorspace models. Refer to the 127 ``sRGB Conversion'' sections of the OpenGL 4.6 and 128 OpenGL ES 3.2 Specifications for more information. 129 </p> 130 </dd> 131 <dt> 132 <span class="term"> 133 <code class="constant">EGL_HEIGHT</code> 134 </span> 135 </dt> 136 <dd> 137 <p> 138 Specifies the required height of the pixel buffer 139 surface. The default value is 140 <code class="constant">0</code>. 141 </p> 142 </dd> 143 <dt> 144 <span class="term"> 145 <code class="constant">EGL_LARGEST_PBUFFER</code> 146 </span> 147 </dt> 148 <dd> 149 <p> 150 Requests the largest available pixel buffer surface 151 when the allocation would otherwise fail. Use 152 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 153 to retrieve the dimensions of the allocated pixel 154 buffer. The default value is 155 <code class="constant">EGL_FALSE</code>. 156 </p> 157 </dd> 158 <dt> 159 <span class="term"> 160 <code class="constant">EGL_MIPMAP_TEXTURE</code> 161 </span> 162 </dt> 163 <dd> 164 <p> 165 Specifies whether storage for mipmaps should be 166 allocated. Space for mipmaps will be set aside if 167 the attribute value is <code class="constant">EGL_TRUE</code> 168 and <code class="constant">EGL_TEXTURE_FORMAT</code> is not 169 <code class="constant">EGL_NO_TEXTURE</code>. The default 170 value is <code class="constant">EGL_FALSE</code>. 171 </p> 172 </dd> 173 <dt> 174 <span class="term"> 175 <code class="constant">EGL_TEXTURE_FORMAT</code> 176 </span> 177 </dt> 178 <dd> 179 <p> 180 Specifies the format of the texture that will be 181 created when a pbuffer is bound to a texture map. 182 Possible values are 183 <code class="constant">EGL_NO_TEXTURE</code>, 184 <code class="constant">EGL_TEXTURE_RGB</code>, and 185 <code class="constant">EGL_TEXTURE_RGBA</code>. The default 186 value is <code class="constant">EGL_NO_TEXTURE</code>. 187 </p> 188 </dd> 189 <dt> 190 <span class="term"> 191 <code class="constant">EGL_TEXTURE_TARGET</code> 192 </span> 193 </dt> 194 <dd> 195 <p> 196 Specifies the target for the texture that will be 197 created when the pbuffer is created with a texture 198 format of <code class="constant">EGL_TEXTURE_RGB</code> or 199 <code class="constant">EGL_TEXTURE_RGBA</code>. Possible 200 values are <code class="constant">EGL_NO_TEXTURE</code>, or 201 <code class="constant">EGL_TEXTURE_2D</code>. The default 202 value is <code class="constant">EGL_NO_TEXTURE</code>. 203 </p> 204 </dd> 205 <dt> 206 <span class="term"> 207 <code class="constant">EGL_VG_ALPHA_FORMAT</code> 208 </span> 209 </dt> 210 <dd> 211 <p> 212 Specifies how alpha values are interpreted by OpenVG 213 when rendering to the surface. If its value is 214 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>, 215 then alpha values are not premultipled. If its value 216 is <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code>, 217 then alpha values are premultiplied. The default 218 value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 219 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>. 220 </p> 221 </dd> 222 <dt> 223 <span class="term"> 224 <code class="constant">EGL_VG_COLORSPACE</code> 225 </span> 226 </dt> 227 <dd> 228 <p> 229 Specifies the color space used by OpenVG when 230 rendering to the surface. If its value is 231 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>, then a 232 non-linear, perceptually uniform color space is 233 assumed, with a corresponding 234 <span class="type">VGImageFormat</span> of form 235 <code class="constant">VG_s*</code>. If its value is 236 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code>, then 237 a linear color space is assumed, with a 238 corresponding <span class="type">VGImageFormat</span> of form 239 <code class="constant">VG_l*</code>. The default value of 240 <code class="constant">EGL_VG_COLORSPACE</code> is 241 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>. 242 </p> 243 </dd> 244 <dt> 245 <span class="term"> 246 <code class="constant">EGL_WIDTH</code> 247 </span> 248 </dt> 249 <dd> 250 <p> 251 Specifies the required width of the pixel buffer 252 surface. The default value is 253 <code class="constant">0</code>. 254 </p> 255 </dd> 256 </dl> 257 </div> 258 <p> 259 Any EGL rendering context that was created with respect to 260 <em class="parameter"><code>config</code></em> can be used to render into the 261 surface. Use 262 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> 263 to attach an EGL rendering context to the surface. 264 </p> 265 <p> 266 Use 267 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 268 to retrieve the dimensions of the allocated pixel buffer 269 surface or the ID of <em class="parameter"><code>config</code></em>. 270 </p> 271 <p> 272 Use <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> 273 to destroy the surface. 274 </p> 275 </div> 276 <div class="refsect1" id="notes"> 277 <h2>Notes</h2> 278 <p> 279 Attribute <code class="constant">EGL_GL_COLORSPACE</code>, and the 280 <code class="constant">EGL_OPENGL_ES3_BIT</code> bit value for attribute 281 <code class="constant">EGL_RENDERABLE_TYPE</code>, are supported only if 282 the EGL version is 1.5 or greater. 283 </p> 284 <p> 285 Attributes 286 <code class="constant">EGL_RENDERABLE_TYPE</code>, 287 <code class="constant">EGL_VG_ALPHA_FORMAT</code>, and 288 <code class="constant">EGL_VG_COLORSPACE</code>, and the 289 corresponding attribute values, are supported only if the 290 EGL version is 1.2 or greater. 291 </p> 292 <p> 293 If the value of <em class="parameter"><code>config</code></em> attribute 294 <code class="constant">EGL_TEXTURE_FORMAT</code> is not 295 <code class="constant">EGL_NO_TEXTURE</code>, then the pbuffer width 296 and height specify the size of the level zero texture image 297 </p> 298 <p> 299 If <code class="constant">EGL_LARGEST_PBUFFER</code> is specified and 300 if the pbuffer will be used as a texture (i.e. the value of 301 <code class="constant">EGL_TEXTURE_TARGET</code> is 302 <code class="constant">EGL_TEXTURE_2D</code>, and the value of 303 <code class="constant">EGL_TEXTURE FORMAT</code> is 304 <code class="constant">EGL_TEXTURE_RGB</code> or 305 <code class="constant">EGL_TEXTURE_RGBA</code>), then the aspect 306 ratio will be preserved and the new width and height will be 307 valid sizes for the texture target (e.g. if the underlying 308 OpenGL ES implementation does not support non-power-of-two 309 textures, both the width and height will be a power of 2). 310 </p> 311 <p> 312 The contents of the depth and stencil buffers may not be 313 preserved when rendering a texture to the pbuffer and 314 switching which image of the texture is rendered to (e.g., 315 switching from rendering one mipmap level to rendering 316 another). 317 </p> 318 </div> 319 <div class="refsect1" id="errors"> 320 <h2>Errors</h2> 321 <p> 322 <code class="constant">EGL_NO_SURFACE</code> is returned if creation of 323 the context fails. 324 </p> 325 <p> 326 <code class="constant">EGL_BAD_DISPLAY</code> is generated if 327 <em class="parameter"><code>display</code></em> is not an EGL display connection. 328 </p> 329 <p> 330 <code class="constant">EGL_NOT_INITIALIZED</code> is generated if 331 <em class="parameter"><code>display</code></em> has not been initialized. 332 </p> 333 <p> 334 <code class="constant">EGL_BAD_CONFIG</code> is generated if 335 <em class="parameter"><code>config</code></em> is not an EGL frame buffer configuration. 336 </p> 337 <p> 338 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 339 <em class="parameter"><code>attrib_list</code></em> contains an invalid pixel 340 buffer attribute or if an attribute value is not recognized 341 or out of range. 342 </p> 343 <p> 344 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 345 <em class="parameter"><code>attrib_list</code></em> contains any of the 346 attributes <code class="constant">EGL_MIPMAP_TEXTURE</code>, 347 <code class="constant">EGL_TEXTURE_FORMAT</code>, or 348 <code class="constant">EGL_TEXTURE_TARGET</code>, and 349 <em class="parameter"><code>config</code></em> does not support OpenGL ES 350 rendering (e.g. the EGL version is 1.2 or later, and the 351 <code class="constant">EGL_RENDERABLE_TYPE</code> attribute of 352 <em class="parameter"><code>config</code></em> does not include at least one 353 of <code class="constant">EGL_OPENGL_ES_BIT</code>, 354 <code class="constant">EGL_OPENGL_ES2_BIT</code>, or 355 <code class="constant">EGL_OPENGL_ES3_BIT</code>), 356 </p> 357 <p> 358 <code class="constant">EGL_BAD_ALLOC</code> is generated if there are not 359 enough resources to allocate the new surface. 360 </p> 361 <p> 362 <code class="constant">EGL_BAD_MATCH</code> is generated if 363 <em class="parameter"><code>config</code></em> does not support rendering to pixel buffers 364 (the <code class="constant">EGL_SURFACE_TYPE</code> attribute does not contain 365 <code class="constant">EGL_PBUFFER_BIT</code>). 366 </p> 367 <p> 368 <code class="constant">EGL_BAD_MATCH</code> is generated if the 369 <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is not 370 <code class="constant">EGL_NO_TEXTURE</code>, and 371 <code class="constant">EGL_WIDTH</code> and/or 372 <code class="constant">EGL_HEIGHT</code> specify an invalid size 373 (e.g., the texture size is not a power of 2, and the 374 underlying OpenGL ES implementation does not support 375 non-power-of-two textures). 376 </p> 377 <p> 378 <code class="constant">EGL_BAD_MATCH</code> is generated if 379 the <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is 380 <code class="constant">EGL_NO_TEXTURE</code>, and 381 <code class="constant">EGL_TEXTURE_TARGET</code> is something other 382 than <code class="constant">EGL_NO_TEXTURE</code>; or, 383 <code class="constant">EGL_TEXTURE_FORMAT</code> is something other 384 than <code class="constant">EGL_NO_TEXTURE</code>, and 385 <code class="constant">EGL_TEXTURE_TARGET</code> is 386 <code class="constant">EGL_NO_TEXTURE</code>. 387 </p> 388 <p> 389 <code class="constant">EGL_BAD_MATCH</code> is generated if 390 <em class="parameter"><code>config</code></em> does not support the specified 391 OpenVG alpha format attribute (the value of 392 <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 393 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code> and the 394 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE_BIT</code> is not set 395 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 396 <em class="parameter"><code>config</code></em>) or colorspace attribute (the 397 value of <code class="constant">EGL_VG_COLORSPACE</code> is 398 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code> and the 399 <code class="constant">EGL_VG_COLORSPACE_LINEAR_IT</code> is not set 400 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 401 <em class="parameter"><code>config</code></em>). 402 </p> 403 </div> 404 <div class="refsect1" id="seealso"> 405 <h2>See Also</h2> 406 <p> 407 <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, 408 <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, 409 <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, 410 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, 411 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 412 </p> 413 </div> 414 <p> 415 </p> 416 <div class="refsect3" id="copyright"> 417 <img src="KhronosLogo.jpg"/> 418 <p> 419 Copyright © 2003-2014 The Khronos Group Inc. 420 Permission is hereby granted, free of charge, to any person obtaining a 421 copy of this software and/or associated documentation files (the 422 "Materials"), to deal in the Materials without restriction, including 423 without limitation the rights to use, copy, modify, merge, publish, 424 distribute, sublicense, and/or sell copies of the Materials, and to 425 permit persons to whom the Materials are furnished to do so, subject to 426 the condition that this copyright notice and permission notice shall be included 427 in all copies or substantial portions of the Materials. 428 </p> 429 </div> 430 <p> 431</p> 432 </div> 433 <footer/> 434 </body> 435</html> 436
