eglMakeCurrent - EGL Reference Pages

Name

eglMakeCurrent — + attach an EGL rendering context to EGL surfaces +

C Specification

+ + + + + + + + + + + + + + + + + +

+ `EGLBoolean eglMakeCurrent(` +	EGLDisplay `display`,
	EGLSurface `draw`,
	EGLSurface `read`,
	EGLContext `context)`;

Parameters

+ + + display + + +: +
Specifies the EGL display connection.
+
+ + + draw + + +: +
Specifies the EGL draw surface.
+
+ + + read + + +: +
Specifies the EGL read surface.
+
+ + + context + + +: +
Specifies the EGL rendering context + to be attached to the surfaces. +
+

Description

+ eglMakeCurrent binds context + to the current rendering thread and to the draw + and read surfaces. +

+ For an OpenGL or OpenGL ES context, draw + is used for all operations except for any pixel data read back or copied + (glReadPixels, + glCopyTexImage2D, and + glCopyTexSubImage2D), + which is taken from the frame buffer values of + read. Note that the same + EGLSurface may be specified for both draw and read. +

+ For an OpenVG context, the same EGLSurface must be + specified for both draw and + read. +

+ If the calling thread has already a current rendering context of + the same client API type as context, then + that context is flushed and marked as no longer current. + context is then made the current context + for the calling thread. For purposes of + eglMakeCurrent, the client API type of all + OpenGL ES and OpenGL contexts is considered the same. In other + words, if any OpenGL ES context is currently bound and + context is an OpenGL context, or if any + OpenGL context is currently bound and + context is an OpenGL ES context, the + currently bound context will be made no longer current and + context will be made current. +

+ OpenGL and OpenGL ES buffer mappings created by e.g. + glMapBuffer are not affected by + eglMakeCurrent; they persist whether the + context owning the buffer is current or not. +

+ If draw is destroyed after + eglMakeCurrent is called, then subsequent + rendering commands will be processed and the context state will + be updated, but the surface contents become undefined. If + read is destroyed after + eglMakeCurrent then pixel values + read from the framebuffer (e.g., as + result of calling glReadPixels) are undefined. If a native + window or pixmap underlying the draw or + read surfaces is destroyed, rendering and + readback are handled as above. +

+ To release the current context without assigning a new one, set + context to + EGL_NO_CONTEXT and set + draw and read to + EGL_NO_SURFACE . The currently bound + context for the client API specified by the current rendering + API is flushed and marked as no longer current, and there will + be no current context for that client API after + eglMakeCurrent returns. This is the only + case in which eglMakeCurrent respects the + current rendering API. In all other cases, the client API + affected is determined by context. This + is the only case where an uninitialized display may be passed to + eglMakeCurrent. +

+ If ctx is not EGL_NO_CONTEXT, then both + draw and read must + not be EGL_NO_SURFACE unless + context is a context which supports being + bound without read and draw surfaces. In this case the context + is made current without a default framebuffer. The meaning of + this is defined by the client API of the supporting context (see + chapter 4 of the OpenGL 3.0 Specification, and the + GL_OES_surfaceless_context OpenGL ES + extension.). +

+ The first time a OpenGL or OpenGL ES context is made current the + viewport and scissor dimensions are set to the size of the + draw surface (as though + glViewport(0,0,w,h) and + glScissor(0,0,w,h) + were called, where w and + h are the width and height of the + surface, respectively). However, the viewport and scissor + dimensions are not modified when context + is subsequently made current. The client is responsible for + resetting the viewport and scissor in this case. +

+ The first time context is made current, + if it is without a default framebuffer (e.g. both + draw and read are + EGL_NO_SURFACE ), then the viewport and + scissor regions are set as though + glViewport(0,0,0,0) and + glScissor(0,0,0,0) were called. +

+ Implementations may delay allocation of auxiliary buffers for a + surface until they are required by a context (which may result + in the EGL_BAD_ALLOC error described + above). Once allocated, however, auxiliary buffers and their + contents persist until a surface is deleted. +

+ Use + eglGetCurrentContext, + eglGetCurrentDisplay, and + eglGetCurrentSurface + to query the current rendering context and associated display connection and surfaces. +

Errors

+ If draw or read + are not compatible with context, then an + EGL_BAD_MATCH error is generated. +

+ If context is current to some other + thread, or if either draw or + read are bound to contexts in another + thread, an EGL_BAD_ACCESS error is + generated. +

+ If binding context would exceed the + number of current contexts of that client API type supported by + the implementation, an EGL_BAD_ACCESS error + is generated. +

+ If either draw or + read are pbuffers created with + eglCreatePbufferFromClientBuffer, and the + underlying bound client API buffers are in use by the client API + that created them, an EGL_BAD_ACCESS error + is generated. +

+ If context is not a valid context and is + not EGL_NO_CONTEXT, an + EGL_BAD_CONTEXT error is generated. +

+ If either draw or + read are not valid EGL surfaces and are + not EGL_NO_SURFACE, an + EGL_BAD_SURFACE error is generated. +

+ If context is + EGL_NO_CONTEXT and either + draw or read are + not EGL_NO_SURFACE, an + EGL_BAD_MATCH error is generated. +

+ If either of draw or + read is a valid surface and the other is + EGL_NO_SURFACE, an + EGL_BAD_MATCH error is generated. +

+ If context does not support being bound + without read and + draw surfaces, and both + draw and read are + EGL_NO_SURFACE, an + EGL_BAD_MATCH error is generated. +

+ If a native window underlying either draw + or read is no longer valid, an + EGL_BAD_NATIVE_WINDOW error is generated. +

+ If draw and read + cannot fit into graphics memory simultaneously, an + EGL_BAD_MATCH error is generated. +

+ If the previous context of the calling thread has unflushed + commands, and the previous surface is no longer valid, an + EGL_BAD_CURRENT_SURFACE error is generated. +

+ If the ancillary buffers for draw and + read cannot be allocated, an + EGL_BAD_ALLOC error is generated. +

+ If a power management event has occurred, an + EGL_CONTEXT_LOST error is generated. +

+ If any of the following are true: + +

+
+ context is not + EGL_NO_CONTEXT +
+
+
+ read is not + EGL_NO_SURFACE +
+
+
+ draw is not + EGL_NO_SURFACE +
+

+ + then an EGL_NOT_INITIALIZED error is + generated if display is a valid but + uninitialized display. +

+ As with other commands taking EGLDisplay + parameters, if display is not a valid + EGLDisplay handle, an + EGL_BAD_DISPLAY error is generated. (Some + implementations have chosen to allow + EGL_NO_DISPLAY as a valid + display parameter for + eglMakeCurrent. This behavior is not + portable to all EGL implementations, and should be considered as + an undocumented vendor extension). +