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.78.1"/> 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_HEIGHT</code> 104 </span> 105 </dt> 106 <dd> 107 <p> 108 Specifies the required height of the pixel buffer 109 surface. The default value is 110 <code class="constant">0</code>. 111 </p> 112 </dd> 113 <dt> 114 <span class="term"> 115 <code class="constant">EGL_LARGEST_PBUFFER</code> 116 </span> 117 </dt> 118 <dd> 119 <p> 120 Requests the largest available pixel buffer surface 121 when the allocation would otherwise fail. Use 122 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 123 to retrieve the dimensions of the allocated pixel 124 buffer. The default value is 125 <code class="constant">EGL_FALSE</code>. 126 </p> 127 </dd> 128 <dt> 129 <span class="term"> 130 <code class="constant">EGL_MIPMAP_TEXTURE</code> 131 </span> 132 </dt> 133 <dd> 134 <p> 135 Specifies whether storage for mipmaps should be 136 allocated. Space for mipmaps will be set aside if 137 the attribute value is <code class="constant">EGL_TRUE</code> 138 and <code class="constant">EGL_TEXTURE_FORMAT</code> is not 139 <code class="constant">EGL_NO_TEXTURE</code>. The default 140 value is <code class="constant">EGL_FALSE</code>. 141 </p> 142 </dd> 143 <dt> 144 <span class="term"> 145 <code class="constant">EGL_TEXTURE_FORMAT</code> 146 </span> 147 </dt> 148 <dd> 149 <p> 150 Specifies the format of the texture that will be 151 created when a pbuffer is bound to a texture map. 152 Possible values are 153 <code class="constant">EGL_NO_TEXTURE</code>, 154 <code class="constant">EGL_TEXTURE_RGB</code>, and 155 <code class="constant">EGL_TEXTURE_RGBA</code>. The default 156 value is <code class="constant">EGL_NO_TEXTURE</code>. 157 </p> 158 </dd> 159 <dt> 160 <span class="term"> 161 <code class="constant">EGL_TEXTURE_TARGET</code> 162 </span> 163 </dt> 164 <dd> 165 <p> 166 Specifies the target for the texture that will be 167 created when the pbuffer is created with a texture 168 format of <code class="constant">EGL_TEXTURE_RGB</code> or 169 <code class="constant">EGL_TEXTURE_RGBA</code>. Possible 170 values are <code class="constant">EGL_NO_TEXTURE</code>, or 171 <code class="constant">EGL_TEXTURE_2D</code>. The default 172 value is <code class="constant">EGL_NO_TEXTURE</code>. 173 </p> 174 </dd> 175 <dt> 176 <span class="term"> 177 <code class="constant">EGL_VG_ALPHA_FORMAT</code> 178 </span> 179 </dt> 180 <dd> 181 <p> 182 Specifies how alpha values are interpreted by OpenVG 183 when rendering to the surface. If its value is 184 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>, 185 then alpha values are not premultipled. If its value 186 is <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code>, 187 then alpha values are premultiplied. The default 188 value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 189 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>. 190 </p> 191 </dd> 192 <dt> 193 <span class="term"> 194 <code class="constant">EGL_VG_COLORSPACE</code> 195 </span> 196 </dt> 197 <dd> 198 <p> 199 Specifies the color space used by OpenVG when 200 rendering to the surface. If its value is 201 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>, then a 202 non-linear, perceptually uniform color space is 203 assumed, with a corresponding 204 <span class="type">VGImageFormat</span> of form 205 <code class="constant">VG_s*</code>. If its value is 206 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code>, then 207 a linear color space is assumed, with a 208 corresponding <span class="type">VGImageFormat</span> of form 209 <code class="constant">VG_l*</code>. The default value of 210 <code class="constant">EGL_VG_COLORSPACE</code> is 211 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>. 212 </p> 213 </dd> 214 <dt> 215 <span class="term"> 216 <code class="constant">EGL_WIDTH</code> 217 </span> 218 </dt> 219 <dd> 220 <p> 221 Specifies the required width of the pixel buffer 222 surface. The default value is 223 <code class="constant">0</code>. 224 </p> 225 </dd> 226 </dl> 227 </div> 228 <p> 229 Any EGL rendering context that was created with respect to 230 <em class="parameter"><code>config</code></em> can be used to render into the 231 surface. Use 232 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> 233 to attach an EGL rendering context to the surface. 234 </p> 235 <p> 236 Use 237 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 238 to retrieve the dimensions of the allocated pixel buffer 239 surface or the ID of <em class="parameter"><code>config</code></em>. 240 </p> 241 <p> 242 Use <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> 243 to destroy the surface. 244 </p> 245 </div> 246 <div class="refsect1" id="notes"> 247 <h2>Notes</h2> 248 <p> 249 Attributes 250 <code class="constant">EGL_RENDERABLE_TYPE</code>, 251 <code class="constant">EGL_VG_ALPHA_FORMAT</code>, and 252 <code class="constant">EGL_VG_COLORSPACE</code>, and the 253 corresponding attribute values, are supported only if the 254 EGL version is 1.2 or greater. 255 </p> 256 <p> 257 If the value of <em class="parameter"><code>config</code></em> attribute 258 <code class="constant">EGL_TEXTURE_FORMAT</code> is not 259 <code class="constant">EGL_NO_TEXTURE</code>, then the pbuffer width 260 and height specify the size of the level zero texture image 261 </p> 262 <p> 263 If <code class="constant">EGL_LARGEST_PBUFFER</code> is specified and 264 if the pbuffer will be used as a texture (i.e. the value of 265 <code class="constant">EGL_TEXTURE_TARGET</code> is 266 <code class="constant">EGL_TEXTURE_2D</code>, and the value of 267 <code class="constant">EGL_TEXTURE FORMAT</code> is 268 <code class="constant">EGL_TEXTURE_RGB</code> or 269 <code class="constant">EGL_TEXTURE_RGBA</code>), then the aspect 270 ratio will be preserved and the new width and height will be 271 valid sizes for the texture target (e.g. if the underlying 272 OpenGL ES implementation does not support non-power-of-two 273 textures, both the width and height will be a power of 2). 274 </p> 275 <p> 276 The contents of the depth and stencil buffers may not be 277 preserved when rendering a texture to the pbuffer and 278 switching which image of the texture is rendered to (e.g., 279 switching from rendering one mipmap level to rendering 280 another). 281 </p> 282 </div> 283 <div class="refsect1" id="errors"> 284 <h2>Errors</h2> 285 <p> 286 <code class="constant">EGL_NO_SURFACE</code> is returned if creation of 287 the context fails. 288 </p> 289 <p> 290 <code class="constant">EGL_BAD_DISPLAY</code> is generated if 291 <em class="parameter"><code>display</code></em> is not an EGL display connection. 292 </p> 293 <p> 294 <code class="constant">EGL_NOT_INITIALIZED</code> is generated if 295 <em class="parameter"><code>display</code></em> has not been initialized. 296 </p> 297 <p> 298 <code class="constant">EGL_BAD_CONFIG</code> is generated if 299 <em class="parameter"><code>config</code></em> is not an EGL frame buffer configuration. 300 </p> 301 <p> 302 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 303 <em class="parameter"><code>attrib_list</code></em> contains an invalid pixel 304 buffer attribute or if an attribute value is not recognized 305 or out of range. 306 </p> 307 <p> 308 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 309 <em class="parameter"><code>attrib_list</code></em> contains any of the 310 attributes <code class="constant">EGL_MIPMAP_TEXTURE</code>, 311 <code class="constant">EGL_TEXTURE_FORMAT</code>, or 312 <code class="constant">EGL_TEXTURE_TARGET</code>, and 313 <em class="parameter"><code>config</code></em> does not support OpenGL ES 314 rendering (e.g. the EGL version is 1.2 or later, and the 315 <code class="constant">EGL_RENDERABLE_TYPE</code> attribute of 316 <em class="parameter"><code>config</code></em> does not include at least one 317 of <code class="constant">EGL_OPENGL_ES_BIT</code> or 318 <code class="constant">EGL_OPENGL_ES2_BIT</code>). 319 </p> 320 <p> 321 <code class="constant">EGL_BAD_ALLOC</code> is generated if there are not 322 enough resources to allocate the new surface. 323 </p> 324 <p> 325 <code class="constant">EGL_BAD_MATCH</code> is generated if 326 <em class="parameter"><code>config</code></em> does not support rendering to pixel buffers 327 (the <code class="constant">EGL_SURFACE_TYPE</code> attribute does not contain 328 <code class="constant">EGL_PBUFFER_BIT</code>). 329 </p> 330 <p> 331 <code class="constant">EGL_BAD_MATCH</code> is generated if the 332 <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is not 333 <code class="constant">EGL_NO_TEXTURE</code>, and 334 <code class="constant">EGL_WIDTH</code> and/or 335 <code class="constant">EGL_HEIGHT</code> specify an invalid size 336 (e.g., the texture size is not a power of 2, and the 337 underlying OpenGL ES implementation does not support 338 non-power-of-two textures). 339 </p> 340 <p> 341 <code class="constant">EGL_BAD_MATCH</code> is generated if 342 the <code class="constant">EGL_TEXTURE_FORMAT</code> attribute is 343 <code class="constant">EGL_NO_TEXTURE</code>, and 344 <code class="constant">EGL_TEXTURE_TARGET</code> is something other 345 than <code class="constant">EGL_NO_TEXTURE</code>; or, 346 <code class="constant">EGL_TEXTURE_FORMAT</code> is something other 347 than <code class="constant">EGL_NO_TEXTURE</code>, and 348 <code class="constant">EGL_TEXTURE_TARGET</code> is 349 <code class="constant">EGL_NO_TEXTURE</code>. 350 </p> 351 <p> 352 <code class="constant">EGL_BAD_MATCH</code> is generated if 353 <em class="parameter"><code>config</code></em> does not support the specified 354 OpenVG alpha format attribute (the value of 355 <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 356 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code> and the 357 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE_BIT</code> is not set 358 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 359 <em class="parameter"><code>config</code></em>) or colorspace attribute (the 360 value of <code class="constant">EGL_VG_COLORSPACE</code> is 361 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code> and the 362 <code class="constant">EGL_VG_COLORSPACE_LINEAR_IT</code> is not set 363 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 364 <em class="parameter"><code>config</code></em>). 365 </p> 366 </div> 367 <div class="refsect1" id="seealso"> 368 <h2>See Also</h2> 369 <p> 370 <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, 371 <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, 372 <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, 373 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, 374 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 375 </p> 376 </div> 377 <p> 378 </p> 379 <div class="refsect3" id="copyright"> 380 <img src="KhronosLogo.jpg"/> 381 <p> 382 Copyright © 2003-2014 The Khronos Group Inc. 383 Permission is hereby granted, free of charge, to any person obtaining a 384 copy of this software and/or associated documentation files (the 385 "Materials"), to deal in the Materials without restriction, including 386 without limitation the rights to use, copy, modify, merge, publish, 387 distribute, sublicense, and/or sell copies of the Materials, and to 388 permit persons to whom the Materials are furnished to do so, subject to 389 the condition that this copyright notice and permission notice shall be included 390 in all copies or substantial portions of the Materials. 391 </p> 392 </div> 393 <p> 394</p> 395 </div> 396 <footer/> 397 </body> 398</html> 399
