eglMakeCurrent — attach an EGL rendering context to EGL surfaces
EGLBoolean eglMakeCurrent(
|
EGLDisplay display, |
EGLSurface draw, | |
EGLSurface read, | |
EGLContext context) ; |
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.
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.
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).
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.