Loading...
Searching...
No Matches
juce::OpenGLContext Class Reference

## Detailed Description

Creates an OpenGL context, which can be attached to a component.

To render some OpenGL, you should create an instance of an OpenGLContext, and call attachTo() to make it use a component as its render target.

To provide threaded rendering, you can supply an OpenGLRenderer object that will be used to render each frame.

Before your target component or OpenGLRenderer is deleted, you MUST call detach() or delete the OpenGLContext to allow the background thread to stop and the native resources to be freed safely.

See also
  OpenGLRenderer

The documentation for this class was generated from the following file:

- juce_opengl/opengl/juce_OpenGLContext.h

## Public Types

enum | TextureMagnificationFilter { nearest , linear }
| Texture magnification filters, used by setTextureMagnificationFilter(). More...
enum | OpenGLVersion { defaultGLVersion = 0 , openGL3_2 , openGL4_1 , openGL4_3 }
| OpenGL versions, used by setOpenGLVersionRequired(). More...

## Public Member Functions

| OpenGLContext ()
| ~OpenGLContext ()
| Destructor.
void | setRenderer (OpenGLRenderer *) noexcept
| Gives the context an OpenGLRenderer to use to do the drawing.
void | attachTo (Component &)
| Attaches the context to a target component.
void | detach ()
| Detaches the context from its target component and deletes any native resources.
bool | isAttached () const noexcept
| Returns true if the context is attached to a component and is on-screen.
Component * | getTargetComponent () const noexcept
| Returns the component to which this context is currently attached, or nullptr.
void | setPixelFormat (const OpenGLPixelFormat &preferredPixelFormat) noexcept
| Sets the pixel format which you'd like to use for the target GL surface.
void | setTextureMagnificationFilter (TextureMagnificationFilter magFilterMode) noexcept
| Sets the texture magnification filter.
void | setNativeSharedContext (void *nativeContextToShareWith) noexcept
| Provides a context with which you'd like this context's resources to be shared.
void | setMultisamplingEnabled (bool) noexcept
| Enables multisampling on platforms where this is implemented.
bool | areShadersAvailable () const
| Returns true if shaders can be used in this context.
bool | isTextureNpotSupported () const
| Returns true if non-power-of-two textures are supported in this context.
void | setOpenGLVersionRequired (OpenGLVersion) noexcept
| Sets a preference for the version of GL that this context should use, if possible.
void | setComponentPaintingEnabled (bool shouldPaintComponent) noexcept
| Enables or disables the use of the GL context to perform 2D rendering of the component to which it is attached.
void | setContinuousRepainting (bool shouldContinuouslyRepaint) noexcept
| Enables or disables continuous repainting.
void | triggerRepaint ()
| Asynchronously causes a repaint to be made.
ReferenceCountedObject * | getAssociatedObject (const char *name) const
| This retrieves an object that was previously stored with setAssociatedObject().
void | setAssociatedObject (const char *name, ReferenceCountedObject *newObject)
| Attaches a named object to the context, which will be deleted when the context is destroyed.
bool | makeActive () const noexcept
| Makes this context the currently active one.
bool | isActive () const noexcept
| Returns true if this context is currently active for the calling thread.
void | swapBuffers ()
| Swaps the buffers (if the context can do this).
bool | setSwapInterval (int numFramesPerSwap)
| Sets whether the context checks the vertical sync before swapping.
int | getSwapInterval () const
| Returns the current swap-sync interval.
template<typename T>
void | executeOnGLThread (T &&functor, bool blockUntilFinished)
| Execute a lambda, function or functor on the OpenGL thread with an active context.
double | getRenderingScale () const noexcept
| Returns a scale factor that relates the context component's size to the number of physical pixels it covers on the screen.
unsigned int | getFrameBufferID () const noexcept
| If this context is backed by a frame buffer, this returns its ID number, or 0 if the context does not use a framebuffer.
void * | getRawContext () const noexcept
| Returns an OS-dependent handle to some kind of underlying OS-provided GL context.
bool | isCoreProfile () const
| Returns true if this context is using the core profile.
void | copyTexture (const Rectangle< int > &targetClipArea, const Rectangle< int > &anchorPosAndTextureSize, int contextWidth, int contextHeight, bool textureOriginIsBottomLeft, bool blend=true)
| Draws the currently selected texture into this context at its original size.
void | setImageCacheSize (size_t cacheSizeBytes) noexcept
| Changes the amount of GPU memory that the internal cache for Images is allowed to use.
size_t | getImageCacheSize () const noexcept
| Returns the amount of GPU memory that the internal cache for Images is allowed to use.

## Static Public Member Functions

static OpenGLContext * | getContextAttachedTo (Component &component) noexcept
| If the given component has an OpenGLContext attached, then this will return it.
static void | deactivateCurrentContext ()
| If any context is active on the current thread, this deactivates it.
static OpenGLContext * | getCurrentContext ()
| Returns the context that's currently in active use by the calling thread, or nullptr if no context is active.

## Public Attributes

OpenGLExtensionFunctions | extensions
| This structure holds a set of dynamically loaded GL functions for use on this context.

## Member Enums

## TextureMagnificationFilter

enum juce::OpenGLContext::TextureMagnificationFilter

Texture magnification filters, used by setTextureMagnificationFilter().

Enumerator
nearest |
linear |

## OpenGLVersion

enum juce::OpenGLContext::OpenGLVersion

OpenGL versions, used by setOpenGLVersionRequired().

The Core profile doesn't include some legacy functionality, including the fixed-function pipeline.

The Compatibility profile is backwards-compatible, and includes functionality deprecated in the Core profile. However, not all implementations provide compatibility profiles targeting later versions of OpenGL. To run on the broadest range of hardware, using the 3.2 Core profile is recommended.

Enumerator
defaultGLVersion | Whatever the device decides to give us, normally a compatibility profile.
openGL3_2 | 3.2 Core profile
openGL4_1 | 4.1 Core profile, the latest supported by macOS at time of writing
openGL4_3 | 4.3 Core profile, will enable improved debugging support when building in Debug

## Constructors and Destructors

## OpenGLContext()

juce::OpenGLContext::OpenGLContext | ( |  | ) |

Referenced by getContextAttachedTo(), and getCurrentContext().

## ~OpenGLContext()

juce::OpenGLContext::~OpenGLContext | ( |  | ) |

Destructor.

## Member Functions

## setRenderer()

void juce::OpenGLContext::setRenderer | ( | OpenGLRenderer * |  | ) |

noexcept

Gives the context an OpenGLRenderer to use to do the drawing.

The object that you give it will not be owned by the context, so it's the caller's responsibility to manage its lifetime and make sure that it doesn't get deleted while the context may be using it. To stop the context using a renderer, just call this method with a null pointer. Note: This must be called BEFORE attaching your context to a target component!

## attachTo()

void juce::OpenGLContext::attachTo | ( | Component & |  | ) |

Attaches the context to a target component.

If the component is not fully visible, this call will wait until the component is shown before actually creating a native context for it.

When a native context is created, a thread is started, and will be used to call the OpenGLRenderer methods. The context will be floated above the target component, and when the target moves, it will track it. If the component is hidden/shown, the context may be deleted and re-created.

## detach()

void juce::OpenGLContext::detach | ( |  | ) |

Detaches the context from its target component and deletes any native resources.

If the context has not been attached, this will do nothing. Otherwise, it will block until the context and its thread have been cleaned up.

## isAttached()

bool juce::OpenGLContext::isAttached | ( |  | ) | const

noexcept

Returns true if the context is attached to a component and is on-screen.

Note that if you call attachTo() for a non-visible component, this method will return false until the component is made visible.

## getTargetComponent()

Component * juce::OpenGLContext::getTargetComponent | ( |  | ) | const

noexcept

Returns the component to which this context is currently attached, or nullptr.

References getTargetComponent().

Referenced by getTargetComponent().

## getContextAttachedTo()

OpenGLContext * juce::OpenGLContext::getContextAttachedTo | ( | Component & | component | ) |

static noexcept

If the given component has an OpenGLContext attached, then this will return it.

References getContextAttachedTo(), and OpenGLContext().

Referenced by getContextAttachedTo().

## setPixelFormat()

void juce::OpenGLContext::setPixelFormat | ( | const OpenGLPixelFormat & | preferredPixelFormat | ) |

noexcept

Sets the pixel format which you'd like to use for the target GL surface.

Note: This must be called BEFORE attaching your context to a target component!

References setPixelFormat().

Referenced by setPixelFormat().

## setTextureMagnificationFilter()

void juce::OpenGLContext::setTextureMagnificationFilter | ( | TextureMagnificationFilter | magFilterMode | ) |

noexcept

Sets the texture magnification filter.

By default the texture magnification filter is linear. However, for faster rendering you may want to use the 'nearest' magnification filter. This option will not affect any textures created before this function was called.

## setNativeSharedContext()

void juce::OpenGLContext::setNativeSharedContext | ( | void * | nativeContextToShareWith | ) |

noexcept

Provides a context with which you'd like this context's resources to be shared.

The object passed-in here is a platform-dependent native context object, and must not be deleted while this context may still be using it! To turn off sharing, you can call this method with a null pointer. Note: This must be called BEFORE attaching your context to a target component!

## setMultisamplingEnabled()

void juce::OpenGLContext::setMultisamplingEnabled | ( | bool |  | ) |

noexcept

Enables multisampling on platforms where this is implemented.

If enabling this, you must call this method before attachTo().

## areShadersAvailable()

bool juce::OpenGLContext::areShadersAvailable | ( |  | ) | const

Returns true if shaders can be used in this context.

## isTextureNpotSupported()

bool juce::OpenGLContext::isTextureNpotSupported | ( |  | ) | const

Returns true if non-power-of-two textures are supported in this context.

## setOpenGLVersionRequired()

void juce::OpenGLContext::setOpenGLVersionRequired | ( | OpenGLVersion |  | ) |

noexcept

Sets a preference for the version of GL that this context should use, if possible.

Some platforms may ignore this value.

## setComponentPaintingEnabled()

void juce::OpenGLContext::setComponentPaintingEnabled | ( | bool | shouldPaintComponent | ) |

noexcept

Enables or disables the use of the GL context to perform 2D rendering of the component to which it is attached.

If this is false, then only your OpenGLRenderer will be used to perform any rendering. If true, then each time your target's paint() method needs to be called, an OpenGLGraphicsContext will be used to render it, (after calling your OpenGLRenderer if there is one).

By default this is set to true. If you're not using any paint() method functionality and are doing all your rendering in an OpenGLRenderer, you should disable it to improve performance.

Note: This must be called BEFORE attaching your context to a target component!

## setContinuousRepainting()

void juce::OpenGLContext::setContinuousRepainting | ( | bool | shouldContinuouslyRepaint | ) |

noexcept

Enables or disables continuous repainting.

If set to true, the context will run a loop, re-rendering itself without waiting for triggerRepaint() to be called, at a frequency determined by the swap interval (see setSwapInterval). If false, then after each render callback, it will wait for another call to triggerRepaint() before rendering again. This is disabled by default.

See also
  setSwapInterval

## triggerRepaint()

void juce::OpenGLContext::triggerRepaint | ( |  | ) |

Asynchronously causes a repaint to be made.

## getAssociatedObject()

ReferenceCountedObject * juce::OpenGLContext::getAssociatedObject | ( | const char * | name | ) | const

This retrieves an object that was previously stored with setAssociatedObject().

If no object is found with the given name, this will return nullptr. This method must only be called from within the GL rendering methods.

See also
  setAssociatedObject

References name.

## setAssociatedObject()

void juce::OpenGLContext::setAssociatedObject | ( | const char * | name,
|  | ReferenceCountedObject * | newObject )

Attaches a named object to the context, which will be deleted when the context is destroyed.

This allows you to store an object which will be released before the context is deleted. The main purpose is for caching GL objects such as shader programs, which will become invalid when the context is deleted.

This method must only be called from within the GL rendering methods.

References name.

## makeActive()

bool juce::OpenGLContext::makeActive | ( |  | ) | const

noexcept

Makes this context the currently active one.

You should never need to call this in normal use - the context will already be active when OpenGLRenderer::renderOpenGL() is invoked.

## isActive()

bool juce::OpenGLContext::isActive | ( |  | ) | const

noexcept

Returns true if this context is currently active for the calling thread.

References isActive().

Referenced by isActive().

## deactivateCurrentContext()

void juce::OpenGLContext::deactivateCurrentContext | ( |  | ) |

static

If any context is active on the current thread, this deactivates it.

Note that on some platforms, like Android, this isn't possible.

References deactivateCurrentContext().

Referenced by deactivateCurrentContext().

## getCurrentContext()

OpenGLContext * juce::OpenGLContext::getCurrentContext | ( |  | ) |

static

Returns the context that's currently in active use by the calling thread, or nullptr if no context is active.

References getCurrentContext(), and OpenGLContext().

Referenced by getCurrentContext().

## swapBuffers()

void juce::OpenGLContext::swapBuffers | ( |  | ) |

Swaps the buffers (if the context can do this).

There's normally no need to call this directly - the buffers will be swapped automatically after your OpenGLRenderer::renderOpenGL() method has been called.

References swapBuffers().

Referenced by swapBuffers().

## setSwapInterval()

bool juce::OpenGLContext::setSwapInterval | ( | int | numFramesPerSwap | ) |

Sets whether the context checks the vertical sync before swapping.

The value is the number of frames to allow between buffer-swapping. This is fairly system-dependent, but 0 turns off syncing, 1 makes it swap on frame-boundaries, and greater numbers indicate that it should swap less often.

By default, this will be set to 1.

Returns true if it sets the value successfully - some platforms won't support this setting.

See also
  setContinuousRepainting

References setSwapInterval().

Referenced by setSwapInterval().

## getSwapInterval()

int juce::OpenGLContext::getSwapInterval | ( |  | ) | const

Returns the current swap-sync interval.

See setSwapInterval() for info about the value returned.

References getSwapInterval().

Referenced by getSwapInterval().

## executeOnGLThread()

template<typename T>

void juce::OpenGLContext::executeOnGLThread | ( | T && | functor,
|  | bool | blockUntilFinished )

Execute a lambda, function or functor on the OpenGL thread with an active context.

This method will attempt to execute functor on the OpenGL thread. If blockUntilFinished is true then the method will block until the functor has finished executing.

This function can only be called if the context is attached to a component. Otherwise, this function will assert.

This function is useful when you need to execute house-keeping tasks such as allocating, deallocating textures or framebuffers. As such, the functor will execute without locking the message thread. Therefore, it is not intended for any drawing commands or GUI code. Any GUI code should be executed in the OpenGLRenderer::renderOpenGL callback instead.

References executeOnGLThread().

Referenced by executeOnGLThread().

## getRenderingScale()

double juce::OpenGLContext::getRenderingScale | ( |  | ) | const

inline noexcept

Returns a scale factor that relates the context component's size to the number of physical pixels it covers on the screen.

In special cases it will be the same as Displays::Display::scale, but it also includes AffineTransforms that affect the rendered area, and will be correctly reported not just in standalone applications but plugins as well.

Note that this should only be called during an OpenGLRenderer::renderOpenGL() callback - at other times the value it returns is undefined.

References getRenderingScale().

Referenced by getRenderingScale().

## getFrameBufferID()

unsigned int juce::OpenGLContext::getFrameBufferID | ( |  | ) | const

noexcept

If this context is backed by a frame buffer, this returns its ID number, or 0 if the context does not use a framebuffer.

## getRawContext()

void * juce::OpenGLContext::getRawContext | ( |  | ) | const

noexcept

Returns an OS-dependent handle to some kind of underlying OS-provided GL context.

The exact type of the value returned will depend on the OS and may change if the implementation changes. If you want to use this, digging around in the native code is probably the best way to find out what it is.

References getRawContext().

Referenced by getRawContext().

## isCoreProfile()

bool juce::OpenGLContext::isCoreProfile | ( |  | ) | const

Returns true if this context is using the core profile.

See also
  OpenGLVersion

References isCoreProfile().

Referenced by isCoreProfile().

## copyTexture()

void juce::OpenGLContext::copyTexture | ( | const Rectangle< int > & | targetClipArea,
|  | const Rectangle< int > & | anchorPosAndTextureSize,
|  | int | contextWidth,
|  | int | contextHeight,
|  | bool | textureOriginIsBottomLeft,
|  | bool | blend = true )

Draws the currently selected texture into this context at its original size.

Parameters

  targetClipArea | the target area to draw into (in top-left origin coords)
  anchorPosAndTextureSize | the position of this rectangle is the texture's top-left anchor position in the target space, and the size must be the total size of the texture.
  contextWidth | the width of the context or framebuffer that is being drawn into, used for scaling of the coordinates.
  contextHeight | the height of the context or framebuffer that is being drawn into, used for vertical flipping of the y coordinates.
  textureOriginIsBottomLeft | if true, the texture's origin is treated as being at (0, 0). If false, it is assumed to be (0, 1)
  blend | if true, the texture's alpha is used to blend the texture with transparency on top the context's existing content. If false, the texture is drawn with no alpha, overwriting the content of the context.

References copyTexture().

Referenced by copyTexture().

## setImageCacheSize()

void juce::OpenGLContext::setImageCacheSize | ( | size_t | cacheSizeBytes | ) |

noexcept

Changes the amount of GPU memory that the internal cache for Images is allowed to use.

References setImageCacheSize().

Referenced by setImageCacheSize().

## getImageCacheSize()

size_t juce::OpenGLContext::getImageCacheSize | ( |  | ) | const

noexcept

Returns the amount of GPU memory that the internal cache for Images is allowed to use.

References getImageCacheSize().

Referenced by getImageCacheSize().

## Member Data Documentation

## extensions

OpenGLExtensionFunctions juce::OpenGLContext::extensions

This structure holds a set of dynamically loaded GL functions for use on this context.

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited