Parameters

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:

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).

See Also

glReadPixels, glCopyTexImage2D, glCopyTexSubImage2D, eglCreateContext, eglCreatePbufferSurface, eglCreatePixmapSurface, eglCreateWindowSurface, eglGetCurrentContext, eglGetCurrentDisplay, eglGetCurrentSurface, eglGetDisplay, eglInitialize

Copyright © 2003-2014 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.