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">eglMakeCurrent - 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.1"/> 7 </head> 8 <body> 9 <header/> 10 <div class="refentry" id="eglMakeCurrent"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglMakeCurrent — 15 attach an EGL rendering context to EGL surfaces 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">EGLBoolean <strong class="fsfunc">eglMakeCurrent</strong>(</code> 25 </td> 26 <td>EGLDisplay <var class="pdparam">display</var>, </td> 27 </tr> 28 <tr> 29 <td> </td> 30 <td>EGLSurface <var class="pdparam">draw</var>, </td> 31 </tr> 32 <tr> 33 <td> </td> 34 <td>EGLSurface <var class="pdparam">read</var>, </td> 35 </tr> 36 <tr> 37 <td> </td> 38 <td>EGLContext <var class="pdparam">context</var><code>)</code>;</td> 39 </tr> 40 </table> 41 <div class="funcprototype-spacer"> </div> 42 </div> 43 </div> 44 <div class="refsect1" id="parameters"> 45 <h2>Parameters</h2> 46 <div class="variablelist"> 47 <dl class="variablelist"> 48 <dt> 49 <span class="term"> 50 <em class="parameter"> 51 <code>display</code> 52 </em> 53 </span> 54 </dt> 55 <dd> 56 <p>Specifies the <abbr class="acronym">EGL</abbr> display connection.</p> 57 </dd> 58 <dt> 59 <span class="term"> 60 <em class="parameter"> 61 <code>draw</code> 62 </em> 63 </span> 64 </dt> 65 <dd> 66 <p>Specifies the <abbr class="acronym">EGL</abbr> draw surface.</p> 67 </dd> 68 <dt> 69 <span class="term"> 70 <em class="parameter"> 71 <code>read</code> 72 </em> 73 </span> 74 </dt> 75 <dd> 76 <p>Specifies the <abbr class="acronym">EGL</abbr> read surface.</p> 77 </dd> 78 <dt> 79 <span class="term"> 80 <em class="parameter"> 81 <code>context</code> 82 </em> 83 </span> 84 </dt> 85 <dd> 86 <p>Specifies the <abbr class="acronym">EGL</abbr> rendering context 87 to be attached to the surfaces. 88 </p> 89 </dd> 90 </dl> 91 </div> 92 </div> 93 <div class="refsect1" id="description"> 94 <h2>Description</h2> 95 <p> 96 <code class="function">eglMakeCurrent</code> binds <em class="parameter"><code>context</code></em> 97 to the current rendering thread and to the <em class="parameter"><code>draw</code></em> 98 and <em class="parameter"><code>read</code></em> surfaces. 99 </p> 100 <p> 101 For an OpenGL or OpenGL ES context, <em class="parameter"><code>draw</code></em> 102 is used for all operations except for any pixel data read back or copied 103 (<a class="citerefentry" href="glReadPixels.xhtml"><span class="citerefentry"><span class="refentrytitle">glReadPixels</span></span></a>, 104 <a class="citerefentry" href="glCopyTexImage2D.xhtml"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage2D</span></span></a>, and 105 <a class="citerefentry" href="glCopyTexSubImage2D.xhtml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage2D</span></span></a>), 106 which is taken from the frame buffer values of 107 <em class="parameter"><code>read</code></em>. Note that the same 108 <span class="type">EGLSurface</span> may be specified for both draw and read. 109 </p> 110 <p> 111 For an OpenVG context, the same <span class="type">EGLSurface</span> must be 112 specified for both <em class="parameter"><code>draw</code></em> and 113 <em class="parameter"><code>read</code></em>. 114 </p> 115 <p> 116 If the calling thread has already a current rendering context of 117 the same client API type as <em class="parameter"><code>context</code></em>, then 118 that context is flushed and marked as no longer current. 119 <em class="parameter"><code>context</code></em> is then made the current context 120 for the calling thread. For purposes of 121 <code class="function">eglMakeCurrent</code>, the client API type of all 122 OpenGL ES and OpenGL contexts is considered the same. In other 123 words, if any OpenGL ES context is currently bound and 124 <em class="parameter"><code>context</code></em> is an OpenGL context, or if any 125 OpenGL context is currently bound and 126 <em class="parameter"><code>context</code></em> is an OpenGL ES context, the 127 currently bound context will be made no longer current and 128 <em class="parameter"><code>context</code></em> will be made current. 129 </p> 130 <p> 131 OpenGL and OpenGL ES buffer mappings created by e.g. 132 <code class="function">glMapBuffer</code> are not affected by 133 <code class="function">eglMakeCurrent</code>; they persist whether the 134 context owning the buffer is current or not. 135 </p> 136 <p> 137 If <em class="parameter"><code>draw</code></em> is destroyed after 138 <code class="function">eglMakeCurrent</code> is called, then subsequent 139 rendering commands will be processed and the context state will 140 be updated, but the surface contents become undefined. If 141 <em class="parameter"><code>read</code></em> is destroyed after 142 <code class="function">eglMakeCurrent</code> then pixel values 143 <em class="parameter"><code>read</code></em> from the framebuffer (e.g., as 144 result of calling glReadPixels) are undefined. If a native 145 window or pixmap underlying the <em class="parameter"><code>draw</code></em> or 146 <em class="parameter"><code>read</code></em> surfaces is destroyed, rendering and 147 <em class="parameter"><code>read</code></em>back are handled as above. 148 </p> 149 <p> 150 To release the current context without assigning a new one, set 151 <em class="parameter"><code>context</code></em> to 152 <code class="constant">EGL_NO_CONTEXT</code> and set 153 <em class="parameter"><code>draw</code></em> and <em class="parameter"><code>read</code></em> to 154 <code class="constant">EGL_NO_SURFACE</code> . The currently bound 155 context for the client API specified by the current rendering 156 API is flushed and marked as no longer current, and there will 157 be no current context for that client API after 158 <code class="function">eglMakeCurrent</code> returns. This is the only 159 case in which <code class="function">eglMakeCurrent</code> respects the 160 current rendering API. In all other cases, the client API 161 affected is determined by <em class="parameter"><code>context</code></em>. This 162 is the only case where an uninitialized display may be passed to 163 <code class="function">eglMakeCurrent</code>. 164 </p> 165 <p> 166 If ctx is not <code class="constant">EGL_NO_CONTEXT</code>, then both 167 <em class="parameter"><code>draw</code></em> and <em class="parameter"><code>read</code></em> must 168 not be <code class="constant">EGL_NO_SURFACE</code> unless 169 <em class="parameter"><code>context</code></em> is a context which supports being 170 bound without read and draw surfaces. In this case the context 171 is made current without a default framebuffer. The meaning of 172 this is defined by the client API of the supporting context (see 173 chapter 4 of the OpenGL 3.0 Specification, and the 174 <code class="constant">GL_OES_surfaceless_context</code> OpenGL ES 175 extension.). 176 </p> 177 <p> 178 The first time a OpenGL or OpenGL ES context is made current the 179 viewport and scissor dimensions are set to the size of the 180 <em class="parameter"><code>draw</code></em> surface (as though 181 <code class="function">glViewport</code>(0,0,w,h) and 182 <code class="function">glScissor</code>(0,0,<em class="parameter"><code>w</code></em>,<em class="parameter"><code>h</code></em>) 183 were called, where <em class="parameter"><code>w</code></em> and 184 <em class="parameter"><code>h</code></em> are the width and height of the 185 surface, respectively). However, the viewport and scissor 186 dimensions are not modified when <em class="parameter"><code>context</code></em> 187 is subsequently made current. The client is responsible for 188 resetting the viewport and scissor in this case. 189 </p> 190 <p> 191 The first time <em class="parameter"><code>context</code></em> is made current, 192 if it is without a default framebuffer (e.g. both 193 <em class="parameter"><code>draw</code></em> and <em class="parameter"><code>read</code></em> are 194 <code class="constant">EGL_NO_SURFACE</code> ), then the viewport and 195 scissor regions are set as though 196 <code class="function">glViewport</code>(0,0,0,0) and 197 <code class="function">glScissor</code>(0,0,0,0) were called. 198 </p> 199 <p> 200 Implementations may delay allocation of auxiliary buffers for a 201 surface until they are required by a context (which may result 202 in the <code class="constant">EGL_BAD_ALLOC</code> error described 203 above). Once allocated, however, auxiliary buffers and their 204 contents persist until a surface is deleted. 205 </p> 206 <p> 207 Use 208 <a class="citerefentry" href="eglGetCurrentContext.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentContext</span></span></a>, 209 <a class="citerefentry" href="eglGetCurrentDisplay.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentDisplay</span></span></a>, and 210 <a class="citerefentry" href="eglGetCurrentSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentSurface</span></span></a> 211 to query the current rendering context and associated display connection and surfaces. 212 </p> 213 </div> 214 <div class="refsect1" id="errors"> 215 <h2>Errors</h2> 216 <p> 217 If <em class="parameter"><code>draw</code></em> or <em class="parameter"><code>read</code></em> 218 are not compatible with <em class="parameter"><code>context</code></em>, then an 219 <code class="constant">EGL_BAD_MATCH</code> error is generated. 220 </p> 221 <p> 222 If <em class="parameter"><code>context</code></em> is current to some other 223 thread, or if either <em class="parameter"><code>draw</code></em> or 224 <em class="parameter"><code>read</code></em> are bound to contexts in another 225 thread, an <code class="constant">EGL_BAD_ACCESS</code> error is 226 generated. 227 </p> 228 <p> 229 If binding <em class="parameter"><code>context</code></em> would exceed the 230 number of current contexts of that client API type supported by 231 the implementation, an <code class="constant">EGL_BAD_ACCESS</code> error 232 is generated. 233 </p> 234 <p> 235 If either <em class="parameter"><code>draw</code></em> or 236 <em class="parameter"><code>read</code></em> are pbuffers created with 237 <code class="function">eglCreatePbufferFromClientBuffer</code>, and the 238 underlying bound client API buffers are in use by the client API 239 that created them, an <code class="constant">EGL_BAD_ACCESS</code> error 240 is generated. 241 </p> 242 <p> 243 If <em class="parameter"><code>context</code></em> is not a valid context and is 244 not <code class="constant">EGL_NO_CONTEXT</code>, an 245 <code class="constant">EGL_BAD_CONTEXT</code> error is generated. 246 </p> 247 <p> 248 If either <em class="parameter"><code>draw</code></em> or 249 <em class="parameter"><code>read</code></em> are not valid EGL surfaces and are 250 not <code class="constant">EGL_NO_SURFACE</code>, an 251 <code class="constant">EGL_BAD_SURFACE</code> error is generated. 252 </p> 253 <p> 254 If <em class="parameter"><code>context</code></em> is 255 <code class="constant">EGL_NO_CONTEXT</code> and either 256 <em class="parameter"><code>draw</code></em> or <em class="parameter"><code>read</code></em> are 257 not <code class="constant">EGL_NO_SURFACE</code>, an 258 <code class="constant">EGL_BAD_MATCH</code> error is generated. 259 </p> 260 <p> 261 If either of <em class="parameter"><code>draw</code></em> or 262 <em class="parameter"><code>read</code></em> is a valid surface and the other is 263 <code class="constant">EGL_NO_SURFACE</code>, an 264 <code class="constant">EGL_BAD_MATCH</code> error is generated. 265 </p> 266 <p> 267 If <em class="parameter"><code>context</code></em> does not support being bound 268 without <em class="parameter"><code>read</code></em> and 269 <em class="parameter"><code>draw</code></em> surfaces, and both 270 <em class="parameter"><code>draw</code></em> and <em class="parameter"><code>read</code></em> are 271 <code class="constant">EGL_NO_SURFACE</code>, an 272 <code class="constant">EGL_BAD_MATCH</code> error is generated. 273 </p> 274 <p> 275 If a native window underlying either <em class="parameter"><code>draw</code></em> 276 or <em class="parameter"><code>read</code></em> is no longer valid, an 277 <code class="constant">EGL_BAD_NATIVE_WINDOW</code> error is generated. 278 </p> 279 <p> 280 If <em class="parameter"><code>draw</code></em> and <em class="parameter"><code>read</code></em> 281 cannot fit into graphics memory simultaneously, an 282 <code class="constant">EGL_BAD_MATCH</code> error is generated. 283 </p> 284 <p> 285 If the previous context of the calling thread has unflushed 286 commands, and the previous surface is no longer valid, an 287 <code class="constant">EGL_BAD_CURRENT_SURFACE</code> error is generated. 288 </p> 289 <p> 290 If the ancillary buffers for <em class="parameter"><code>draw</code></em> and 291 <em class="parameter"><code>read</code></em> cannot be allocated, an 292 <code class="constant">EGL_BAD_ALLOC</code> error is generated. 293 </p> 294 <p> 295 If a power management event has occurred, an 296 <code class="constant">EGL_CONTEXT_LOST</code> error is generated. 297 </p> 298 <p> 299 If any of the following are true: 300 301 </p> 302 <div class="itemizedlist"> 303 <ul class="itemizedlist" style="list-style-type: disc; "> 304 <li class="listitem"> 305 <p> 306 <em class="parameter"><code>context</code></em> is not 307 <code class="constant">EGL_NO_CONTEXT</code> 308 </p> 309 </li> 310 <li class="listitem"> 311 <p> 312 <em class="parameter"><code>read</code></em> is not 313 <code class="constant">EGL_NO_SURFACE</code> 314 </p> 315 </li> 316 <li class="listitem"> 317 <p> 318 <em class="parameter"><code>draw</code></em> is not 319 <code class="constant">EGL_NO_SURFACE</code> 320 </p> 321 </li> 322 </ul> 323 </div> 324 <p> 325 326 then an <code class="constant">EGL_NOT_INITIALIZED</code> error is 327 generated if <em class="parameter"><code>display</code></em> is a valid but 328 uninitialized display. 329 </p> 330 <p> 331 As with other commands taking <span class="type">EGLDisplay</span> 332 parameters, if <em class="parameter"><code>display</code></em> is not a valid 333 <span class="type">EGLDisplay</span> handle, an 334 <code class="constant">EGL_BAD_DISPLAY</code> error is generated. (Some 335 implementations have chosen to allow 336 <code class="constant">EGL_NO_DISPLAY</code> as a valid 337 <em class="parameter"><code>display</code></em> parameter for 338 <code class="function">eglMakeCurrent</code>. This behavior is not 339 portable to all EGL implementations, and should be considered as 340 an undocumented vendor extension). 341 </p> 342 </div> 343 <div class="refsect1" id="seealso"> 344 <h2>See Also</h2> 345 <p> 346 <a class="citerefentry" href="glReadPixels.xhtml"><span class="citerefentry"><span class="refentrytitle">glReadPixels</span></span></a>, 347 <a class="citerefentry" href="glCopyTexImage2D.xhtml"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage2D</span></span></a>, 348 <a class="citerefentry" href="glCopyTexSubImage2D.xhtml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage2D</span></span></a>, 349 <a class="citerefentry" href="eglCreateContext.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreateContext</span></span></a>, 350 <a class="citerefentry" href="eglCreatePbufferSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePbufferSurface</span></span></a>, 351 <a class="citerefentry" href="eglCreatePixmapSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreatePixmapSurface</span></span></a>, 352 <a class="citerefentry" href="eglCreateWindowSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreateWindowSurface</span></span></a>, 353 <a class="citerefentry" href="eglGetCurrentContext.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentContext</span></span></a>, 354 <a class="citerefentry" href="eglGetCurrentDisplay.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentDisplay</span></span></a>, 355 <a class="citerefentry" href="eglGetCurrentSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentSurface</span></span></a>, 356 <a class="citerefentry" href="eglGetDisplay.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetDisplay</span></span></a>, 357 <a class="citerefentry" href="eglInitialize.xhtml"><span class="citerefentry"><span class="refentrytitle">eglInitialize</span></span></a> 358 </p> 359 </div> 360 <p> 361 </p> 362 <div class="refsect3" id="copyright"> 363 <img src="KhronosLogo.jpg"/> 364 <p> 365 Copyright © 2003-2014 The Khronos Group Inc. 366 Permission is hereby granted, free of charge, to any person obtaining a 367 copy of this software and/or associated documentation files (the 368 "Materials"), to deal in the Materials without restriction, including 369 without limitation the rights to use, copy, modify, merge, publish, 370 distribute, sublicense, and/or sell copies of the Materials, and to 371 permit persons to whom the Materials are furnished to do so, subject to 372 the condition that this copyright notice and permission notice shall be included 373 in all copies or substantial portions of the Materials. 374 </p> 375 </div> 376 <p> 377</p> 378 </div> 379 <footer/> 380 </body> 381</html> 382
