Only canvas dc<%> and bitmap-dc% objects support OpenGL (always under Windows and Mac OS X, sometimes under X), and in the case of a bitmap-dc%, the context is usable only when the target bitmap is non-monochrome. When the target bitmap for a bitmap-dc% context is changed via set-bitmap, the associated OpenGL context is reset, but the gl-context<%> keeps its identity. Canvas contexts are double buffered, and bitmap contexts are single buffered.

The racket/gui/base library provides no OpenGL routines. Instead, they must be obtained from a separate library, such as sgl. The facilities in racket/gui/base merely manage the current OpenGL context, connecting it to windows and bitmaps.

Only one OpenGL context can be active at a time across all threads and eventspaces. Except under Mac OS X, OpenGL contexts are not protected against interference among threads; that is, if a thread selects one of its OpenGL contexts, then other threads can write into the context via OpenGL commands. However, if all threads issue OpenGL commands only within a thunk passed to call-as-current, then drawing from the separate threads will not interfere, because call-as-current uses a lock to serialize context selection across all threads in Racket.

The method blocks to obtain a lock that protects the global OpenGL context, and it releases the lock when the thunk returns or escapes. The lock is re-entrant, so a nested use of the method in the same thread with the same OpenGL context does not obtain or release the lock.

The lock prevents interference among OpenGL-using threads. If a thread is terminated while holding the context lock, the lock is released. Continuation jumps into the thunk do not grab the lock or set the OpenGL context. See gl-context<%> for more information on interference.

The method accepts an alternate synchronizable event for use while blocking for the context lock; see also sync.

The result of the method call is the result of the thunk if it is called, or the result of the alternate event if it is chosen instead of the context lock.

If ok? returns #f at the time that this method is called, then an exn:fail:contract exception is raised.

If enable-breaks? is true, then the method uses sync/enable-break while blocking for the context-setting lock instead of sync.

A context is unavailable if OpenGL support is disabled at compile time or run time, if the context is associated with a bitmap-dc% with no selected bitmap or with a monochrome selected bitmap, if the context is for a canvas that no longer exists, or if there was a low-level error when preparing the context.