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 `read`back 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).

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