JUCE  v5.1.1-3-g1a0b28c73
JUCE API
OpenGLContext Class Reference

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

#include <juce_OpenGLContext.h>

Collaboration diagram for OpenGLContext:

Classes

struct  AsyncWorker
 
struct  AsyncWorkerFunctor
 
class  NativeContext
 

Public Types

enum  OpenGLVersion {
  defaultGLVersion = 0,
  openGL3_2
}
 OpenGL versions, used by setOpenGLVersionRequired(). More...
 

Public Member Functions

 OpenGLContext ()
 
 ~OpenGLContext ()
 Destructor. More...
 
bool areShadersAvailable () const
 Returns true if shaders can be used in this context. More...
 
void attachTo (Component &)
 Attaches the context to a target component. More...
 
void copyTexture (const Rectangle< int > &targetClipArea, const Rectangle< int > &anchorPosAndTextureSize, int contextWidth, int contextHeight, bool textureOriginIsBottomLeft)
 Draws the currently selected texture into this context at its original size. More...
 
void detach ()
 Detaches the context from its target component and deletes any native resources. More...
 
template<typename T >
void executeOnGLThread (T &&functor, bool blockUntilFinished)
 Execute a lambda, function or functor on the OpenGL thread with an active context. More...
 
ReferenceCountedObjectgetAssociatedObject (const char *name) const
 This retrieves an object that was previously stored with setAssociatedObject(). More...
 
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. More...
 
size_t getImageCacheSize () const noexcept
 Returns the amount of GPU memory that the internal cache for Images is allowed to use. More...
 
void * getRawContext () const noexcept
 Returns an OS-dependent handle to some kind of underlting OS-provided GL context. More...
 
double getRenderingScale () const noexcept
 Returns the scale factor used by the display that is being rendered. More...
 
int getSwapInterval () const
 Returns the current swap-sync interval. More...
 
ComponentgetTargetComponent () const noexcept
 Returns the component to which this context is currently attached, or nullptr. More...
 
bool isActive () const noexcept
 Returns true if this context is currently active for the calling thread. More...
 
bool isAttached () const noexcept
 Returns true if the context is attached to a component and is on-screen. More...
 
bool makeActive () const noexcept
 Makes this context the currently active one. More...
 
void setAssociatedObject (const char *name, ReferenceCountedObject *newObject)
 Attaches a named object to the context, which will be deleted when the context is destroyed. More...
 
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. More...
 
void setContinuousRepainting (bool shouldContinuouslyRepaint) noexcept
 Enables or disables continuous repainting. More...
 
void setImageCacheSize (size_t cacheSizeBytes) noexcept
 Changes the amount of GPU memory that the internal cache for Images is allowed to use. More...
 
void setMultisamplingEnabled (bool) noexcept
 Enables multisampling on platforms where this is implemented. More...
 
void setNativeSharedContext (void *nativeContextToShareWith) noexcept
 Provides a context with which you'd like this context's resources to be shared. More...
 
void setOpenGLVersionRequired (OpenGLVersion) noexcept
 Sets a preference for the version of GL that this context should use, if possible. More...
 
void setPixelFormat (const OpenGLPixelFormat &preferredPixelFormat) noexcept
 Sets the pixel format which you'd like to use for the target GL surface. More...
 
void setRenderer (OpenGLRenderer *) noexcept
 Gives the context an OpenGLRenderer to use to do the drawing. More...
 
bool setSwapInterval (int numFramesPerSwap)
 Sets whether the context checks the vertical sync before swapping. More...
 
void swapBuffers ()
 Swaps the buffers (if the context can do this). More...
 
void triggerRepaint ()
 Asynchronously causes a repaint to be made. More...
 

Static Public Member Functions

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

Public Attributes

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

Private Member Functions

void execute (AsyncWorker::Ptr, bool)
 
CachedImage * getCachedImage () const noexcept
 
void overrideCanBeAttached (bool)
 

Private Attributes

ScopedPointer< Attachment > attachment
 
void * contextToShareWith
 
bool continuousRepaint
 
double currentRenderScale
 
size_t imageCacheMaxSize
 
NativeContextnativeContext
 
OpenGLPixelFormat openGLPixelFormat
 
bool overrideCanAttach
 
bool renderComponents
 
OpenGLRendererrenderer
 
bool useMultisampling
 
OpenGLVersion versionRequired
 

Friends

void componentPeerAboutToChange (Component &, bool)
 

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

Member Enumeration Documentation

◆ OpenGLVersion

OpenGL versions, used by setOpenGLVersionRequired().

Enumerator
defaultGLVersion 
openGL3_2 

Constructor & Destructor Documentation

◆ OpenGLContext()

OpenGLContext::OpenGLContext ( )

◆ ~OpenGLContext()

OpenGLContext::~OpenGLContext ( )

Destructor.

Member Function Documentation

◆ areShadersAvailable()

bool OpenGLContext::areShadersAvailable ( ) const

Returns true if shaders can be used in this context.

◆ attachTo()

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

◆ copyTexture()

void OpenGLContext::copyTexture ( const Rectangle< int > &  targetClipArea,
const Rectangle< int > &  anchorPosAndTextureSize,
int  contextWidth,
int  contextHeight,
bool  textureOriginIsBottomLeft 
)

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

Parameters
targetClipAreathe target area to draw into (in top-left origin coords)
anchorPosAndTextureSizethe 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.
contextWidththe width of the context or framebuffer that is being drawn into, used for scaling of the coordinates.
contextHeightthe height of the context or framebuffer that is being drawn into, used for vertical flipping of the y coordinates.
textureOriginIsBottomLeftif true, the texture's origin is treated as being at (0, 0). If false, it is assumed to be (0, 1)

◆ deactivateCurrentContext()

static void 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.

◆ detach()

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

◆ execute()

void OpenGLContext::execute ( AsyncWorker::Ptr  ,
bool   
)
private

◆ executeOnGLThread()

template<typename T >
void 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 excute 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.

◆ getAssociatedObject()

ReferenceCountedObject* 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

◆ getCachedImage()

CachedImage* OpenGLContext::getCachedImage ( ) const
privatenoexcept

◆ getContextAttachedTo()

static OpenGLContext* OpenGLContext::getContextAttachedTo ( Component component)
staticnoexcept

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

Referenced by componentPeerAboutToChange().

◆ getCurrentContext()

static OpenGLContext* OpenGLContext::getCurrentContext ( )
static

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

◆ getFrameBufferID()

unsigned int 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.

◆ getImageCacheSize()

size_t OpenGLContext::getImageCacheSize ( ) const
noexcept

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

◆ getRawContext()

void* OpenGLContext::getRawContext ( ) const
noexcept

Returns an OS-dependent handle to some kind of underlting 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.

◆ getRenderingScale()

double OpenGLContext::getRenderingScale ( ) const
inlinenoexcept

Returns the scale factor used by the display that is being rendered.

The scale is that of the display - see Desktop::Displays::Display::scale

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

◆ getSwapInterval()

int OpenGLContext::getSwapInterval ( ) const

Returns the current swap-sync interval.

See setSwapInterval() for info about the value returned.

◆ getTargetComponent()

Component* OpenGLContext::getTargetComponent ( ) const
noexcept

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

◆ isActive()

bool OpenGLContext::isActive ( ) const
noexcept

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

◆ isAttached()

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

◆ makeActive()

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

Referenced by OpenGLContext::NativeContext::initialiseOnRenderThread().

◆ overrideCanBeAttached()

void OpenGLContext::overrideCanBeAttached ( bool  )
private

◆ setAssociatedObject()

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

◆ setComponentPaintingEnabled()

void 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 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

◆ setImageCacheSize()

void OpenGLContext::setImageCacheSize ( size_t  cacheSizeBytes)
noexcept

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

◆ setMultisamplingEnabled()

void OpenGLContext::setMultisamplingEnabled ( bool  )
noexcept

Enables multisampling on platforms where this is implemented.

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

◆ setNativeSharedContext()

void 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!

◆ setOpenGLVersionRequired()

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

◆ setPixelFormat()

void 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!

◆ setRenderer()

void 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!

◆ setSwapInterval()

bool 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

◆ swapBuffers()

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

◆ triggerRepaint()

void OpenGLContext::triggerRepaint ( )

Asynchronously causes a repaint to be made.

Referenced by OpenGLContext::NativeContext::dispatchDraw().

Friends And Related Function Documentation

◆ componentPeerAboutToChange

void componentPeerAboutToChange ( Component comp,
bool  shouldSuspend 
)
friend

Member Data Documentation

◆ attachment

ScopedPointer<Attachment> OpenGLContext::attachment
private

◆ contextToShareWith

void* OpenGLContext::contextToShareWith
private

◆ continuousRepaint

bool OpenGLContext::continuousRepaint
private

◆ currentRenderScale

double OpenGLContext::currentRenderScale
private

◆ extensions

OpenGLExtensionFunctions OpenGLContext::extensions

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

◆ imageCacheMaxSize

size_t OpenGLContext::imageCacheMaxSize
private

◆ nativeContext

NativeContext* OpenGLContext::nativeContext
private

◆ openGLPixelFormat

OpenGLPixelFormat OpenGLContext::openGLPixelFormat
private

◆ overrideCanAttach

bool OpenGLContext::overrideCanAttach
private

◆ renderComponents

bool OpenGLContext::renderComponents
private

◆ renderer

OpenGLRenderer* OpenGLContext::renderer
private

◆ useMultisampling

bool OpenGLContext::useMultisampling
private

◆ versionRequired

OpenGLVersion OpenGLContext::versionRequired
private

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