1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglMakeCurrent"> 2 <info> 3 <copyright> 4 <year>2003-2018</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglMakeCurrent</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglMakeCurrent</refname> 14 <refpurpose> 15 attach an EGL rendering context to EGL surfaces 16 </refpurpose> 17 </refnamediv> 18 <refsynopsisdiv> 19 <title>C Specification</title> 20 <funcsynopsis> 21 <funcprototype> 22 <funcdef>EGLBoolean <function>eglMakeCurrent</function></funcdef> 23 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 24 <paramdef>EGLSurface <parameter>draw</parameter></paramdef> 25 <paramdef>EGLSurface <parameter>read</parameter></paramdef> 26 <paramdef>EGLContext <parameter>context</parameter></paramdef> 27 </funcprototype> 28 </funcsynopsis> 29 </refsynopsisdiv> 30 <refsect1 xml:id="parameters"><title>Parameters</title> 31 <variablelist> 32 <varlistentry> 33 <term><parameter>display</parameter></term> 34 <listitem> 35 <para>Specifies the <acronym>EGL</acronym> display connection.</para> 36 </listitem> 37 </varlistentry> 38 <varlistentry> 39 <term><parameter>draw</parameter></term> 40 <listitem> 41 <para>Specifies the <acronym>EGL</acronym> draw surface.</para> 42 </listitem> 43 </varlistentry> 44 <varlistentry> 45 <term><parameter>read</parameter></term> 46 <listitem> 47 <para>Specifies the <acronym>EGL</acronym> read surface.</para> 48 </listitem> 49 </varlistentry> 50 <varlistentry> 51 <term><parameter>context</parameter></term> 52 <listitem> 53 <para>Specifies the <acronym>EGL</acronym> rendering context 54 to be attached to the surfaces. 55 </para> 56 </listitem> 57 </varlistentry> 58 </variablelist> 59 </refsect1> 60 <refsect1 xml:id="description"><title>Description</title> 61 <para> 62 <function>eglMakeCurrent</function> binds <parameter>context</parameter> 63 to the current rendering thread and to the <parameter>draw</parameter> 64 and <parameter>read</parameter> surfaces. 65 </para> 66 <para> 67 For an OpenGL or OpenGL ES context, <parameter>draw</parameter> 68 is used for all operations except for any pixel data read back or copied 69 (<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>, 70 <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>, and 71 <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>), 72 which is taken from the frame buffer values of 73 <parameter>read</parameter>. Note that the same 74 <type>EGLSurface</type> may be specified for both draw and read. 75 </para> 76 <para> 77 For an OpenVG context, the same <type>EGLSurface</type> must be 78 specified for both <parameter>draw</parameter> and 79 <parameter>read</parameter>. 80 </para> 81 <para> 82 If the calling thread has already a current rendering context of 83 the same client API type as <parameter>context</parameter>, then 84 that context is flushed and marked as no longer current. 85 <parameter>context</parameter> is then made the current context 86 for the calling thread. For purposes of 87 <function>eglMakeCurrent</function>, the client API type of all 88 OpenGL ES and OpenGL contexts is considered the same. In other 89 words, if any OpenGL ES context is currently bound and 90 <parameter>context</parameter> is an OpenGL context, or if any 91 OpenGL context is currently bound and 92 <parameter>context</parameter> is an OpenGL ES context, the 93 currently bound context will be made no longer current and 94 <parameter>context</parameter> will be made current. 95 </para> 96 <para> 97 OpenGL and OpenGL ES buffer mappings created by e.g. 98 <function>glMapBuffer</function> are not affected by 99 <function>eglMakeCurrent</function>; they persist whether the 100 context owning the buffer is current or not. 101 </para> 102 <para> 103 If <parameter>draw</parameter> is destroyed after 104 <function>eglMakeCurrent</function> is called, then subsequent 105 rendering commands will be processed and the context state will 106 be updated, but the surface contents become undefined. If 107 <parameter>read</parameter> is destroyed after 108 <function>eglMakeCurrent</function> then pixel values 109 <parameter>read</parameter> from the framebuffer (e.g., as 110 result of calling glReadPixels) are undefined. If a native 111 window or pixmap underlying the <parameter>draw</parameter> or 112 <parameter>read</parameter> surfaces is destroyed, rendering and 113 <parameter>read</parameter>back are handled as above. 114 </para> 115 <para> 116 To release the current context without assigning a new one, set 117 <parameter>context</parameter> to 118 <constant>EGL_NO_CONTEXT</constant> and set 119 <parameter>draw</parameter> and <parameter>read</parameter> to 120 <constant>EGL_NO_SURFACE</constant> . The currently bound 121 context for the client API specified by the current rendering 122 API is flushed and marked as no longer current, and there will 123 be no current context for that client API after 124 <function>eglMakeCurrent</function> returns. This is the only 125 case in which <function>eglMakeCurrent</function> respects the 126 current rendering API. In all other cases, the client API 127 affected is determined by <parameter>context</parameter>. This 128 is the only case where an uninitialized display may be passed to 129 <function>eglMakeCurrent</function>. 130 </para> 131 <para> 132 If ctx is not <constant>EGL_NO_CONTEXT</constant>, then both 133 <parameter>draw</parameter> and <parameter>read</parameter> must 134 not be <constant>EGL_NO_SURFACE</constant> unless 135 <parameter>context</parameter> is a context which supports being 136 bound without read and draw surfaces. In this case the context 137 is made current without a default framebuffer. The meaning of 138 this is defined by the client API of the supporting context (see 139 chapter 4 of the OpenGL 3.0 Specification, and the 140 <constant>GL_OES_surfaceless_context</constant> OpenGL ES 141 extension.). 142 </para> 143 <para> 144 The first time a OpenGL or OpenGL ES context is made current the 145 viewport and scissor dimensions are set to the size of the 146 <parameter>draw</parameter> surface (as though 147 <function>glViewport</function>(0,0,w,h) and 148 <function>glScissor</function>(0,0,<parameter>w</parameter>,<parameter>h</parameter>) 149 were called, where <parameter>w</parameter> and 150 <parameter>h</parameter> are the width and height of the 151 surface, respectively). However, the viewport and scissor 152 dimensions are not modified when <parameter>context</parameter> 153 is subsequently made current. The client is responsible for 154 resetting the viewport and scissor in this case. 155 </para> 156 <para> 157 The first time <parameter>context</parameter> is made current, 158 if it is without a default framebuffer (e.g. both 159 <parameter>draw</parameter> and <parameter>read</parameter> are 160 <constant>EGL_NO_SURFACE</constant> ), then the viewport and 161 scissor regions are set as though 162 <function>glViewport</function>(0,0,0,0) and 163 <function>glScissor</function>(0,0,0,0) were called. 164 </para> 165 <para> 166 Implementations may delay allocation of auxiliary buffers for a 167 surface until they are required by a context (which may result 168 in the <constant>EGL_BAD_ALLOC</constant> error described 169 above). Once allocated, however, auxiliary buffers and their 170 contents persist until a surface is deleted. 171 </para> 172 <para> 173 Use 174 <citerefentry><refentrytitle>eglGetCurrentContext</refentrytitle></citerefentry>, 175 <citerefentry><refentrytitle>eglGetCurrentDisplay</refentrytitle></citerefentry>, and 176 <citerefentry><refentrytitle>eglGetCurrentSurface</refentrytitle></citerefentry> 177 to query the current rendering context and associated display connection and surfaces. 178 </para> 179 </refsect1> 180 <refsect1 xml:id="errors"><title>Errors</title> 181 <para> 182 If <parameter>draw</parameter> or <parameter>read</parameter> 183 are not compatible with <parameter>context</parameter>, then an 184 <constant>EGL_BAD_MATCH</constant> error is generated. 185 </para> 186 <para> 187 If <parameter>context</parameter> is current to some other 188 thread, or if either <parameter>draw</parameter> or 189 <parameter>read</parameter> are bound to contexts in another 190 thread, an <constant>EGL_BAD_ACCESS</constant> error is 191 generated. 192 </para> 193 <para> 194 If binding <parameter>context</parameter> would exceed the 195 number of current contexts of that client API type supported by 196 the implementation, an <constant>EGL_BAD_ACCESS</constant> error 197 is generated. 198 </para> 199 <para> 200 If either <parameter>draw</parameter> or 201 <parameter>read</parameter> are pbuffers created with 202 <function>eglCreatePbufferFromClientBuffer</function>, and the 203 underlying bound client API buffers are in use by the client API 204 that created them, an <constant>EGL_BAD_ACCESS</constant> error 205 is generated. 206 </para> 207 <para> 208 If <parameter>context</parameter> is not a valid context and is 209 not <constant>EGL_NO_CONTEXT</constant>, an 210 <constant>EGL_BAD_CONTEXT</constant> error is generated. 211 </para> 212 <para> 213 If either <parameter>draw</parameter> or 214 <parameter>read</parameter> are not valid EGL surfaces and are 215 not <constant>EGL_NO_SURFACE</constant>, an 216 <constant>EGL_BAD_SURFACE</constant> error is generated. 217 </para> 218 <para> 219 If <parameter>context</parameter> is 220 <constant>EGL_NO_CONTEXT</constant> and either 221 <parameter>draw</parameter> or <parameter>read</parameter> are 222 not <constant>EGL_NO_SURFACE</constant>, an 223 <constant>EGL_BAD_MATCH</constant> error is generated. 224 </para> 225 <para> 226 If either of <parameter>draw</parameter> or 227 <parameter>read</parameter> is a valid surface and the other is 228 <constant>EGL_NO_SURFACE</constant>, an 229 <constant>EGL_BAD_MATCH</constant> error is generated. 230 </para> 231 <para> 232 If <parameter>context</parameter> does not support being bound 233 without <parameter>read</parameter> and 234 <parameter>draw</parameter> surfaces, and both 235 <parameter>draw</parameter> and <parameter>read</parameter> are 236 <constant>EGL_NO_SURFACE</constant>, an 237 <constant>EGL_BAD_MATCH</constant> error is generated. 238 </para> 239 <para> 240 If a native window underlying either <parameter>draw</parameter> 241 or <parameter>read</parameter> is no longer valid, an 242 <constant>EGL_BAD_NATIVE_WINDOW</constant> error is generated. 243 </para> 244 <para> 245 If <parameter>draw</parameter> and <parameter>read</parameter> 246 cannot fit into graphics memory simultaneously, an 247 <constant>EGL_BAD_MATCH</constant> error is generated. 248 </para> 249 <para> 250 If the previous context of the calling thread has unflushed 251 commands, and the previous surface is no longer valid, an 252 <constant>EGL_BAD_CURRENT_SURFACE</constant> error is generated. 253 </para> 254 <para> 255 If the ancillary buffers for <parameter>draw</parameter> and 256 <parameter>read</parameter> cannot be allocated, an 257 <constant>EGL_BAD_ALLOC</constant> error is generated. 258 </para> 259 <para> 260 If a power management event has occurred, an 261 <constant>EGL_CONTEXT_LOST</constant> error is generated. 262 </para> 263 <para> 264 If any of the following are true: 265 266 <itemizedlist> 267 <listitem> 268 <para> 269 <parameter>context</parameter> is not 270 <constant>EGL_NO_CONTEXT</constant> 271 </para> 272 </listitem> 273 <listitem> 274 <para> 275 <parameter>read</parameter> is not 276 <constant>EGL_NO_SURFACE</constant> 277 </para> 278 </listitem> 279 <listitem> 280 <para> 281 <parameter>draw</parameter> is not 282 <constant>EGL_NO_SURFACE</constant> 283 </para> 284 </listitem> 285 </itemizedlist> 286 287 then an <constant>EGL_NOT_INITIALIZED</constant> error is 288 generated if <parameter>display</parameter> is a valid but 289 uninitialized display. 290 </para> 291 <para> 292 As with other commands taking <type>EGLDisplay</type> 293 parameters, if <parameter>display</parameter> is not a valid 294 <type>EGLDisplay</type> handle, an 295 <constant>EGL_BAD_DISPLAY</constant> error is generated. (Some 296 implementations have chosen to allow 297 <constant>EGL_NO_DISPLAY</constant> as a valid 298 <parameter>display</parameter> parameter for 299 <function>eglMakeCurrent</function>. This behavior is not 300 portable to all EGL implementations, and should be considered as 301 an undocumented vendor extension). 302 </para> 303 </refsect1> 304 <refsect1 xml:id="seealso"><title>See Also</title> 305 <para> 306 <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>, 307 <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>, 308 <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>, 309 <citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>, 310 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 311 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>, 312 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>, 313 <citerefentry><refentrytitle>eglGetCurrentContext</refentrytitle></citerefentry>, 314 <citerefentry><refentrytitle>eglGetCurrentDisplay</refentrytitle></citerefentry>, 315 <citerefentry><refentrytitle>eglGetCurrentSurface</refentrytitle></citerefentry>, 316 <citerefentry><refentrytitle>eglGetDisplay</refentrytitle></citerefentry>, 317 <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry> 318 </para> 319 </refsect1> 320 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 321</refentry> 322