A component that contains an OpenGL canvas. More...
Inherits Component.
Public Types | |
| enum | OpenGLType { openGLDefault = 0 } |
Used to select the type of openGL API to use, if more than one choice is available on a particular platform. More... | |
Public Member Functions | |
| OpenGLComponent (OpenGLType type=openGLDefault, bool useBackgroundThread=false) | |
| Creates an OpenGLComponent. | |
| ~OpenGLComponent () | |
| Destructor. | |
| void | setPixelFormat (const OpenGLPixelFormat &formatToUse) |
| Changes the pixel format used by this component. | |
| const OpenGLPixelFormat | getPixelFormat () const |
| Returns the pixel format that this component is currently using. | |
| void | shareWith (OpenGLContext *contextToShareListsWith) |
| Specifies an OpenGL context which should be shared with the one that this component is using. | |
| OpenGLContext * | getShareContext () const noexcept |
| Returns the context that this component is sharing with. | |
| void | swapBuffers () |
| Flips the openGL buffers over. | |
| bool | isUsingDedicatedThread () const noexcept |
| Returns true if the component is performing the rendering on a background thread. | |
| virtual void | renderOpenGL ()=0 |
| This replaces the normal paint() callback - use it to draw your openGL stuff. | |
| virtual void | newOpenGLContextCreated ()=0 |
| This method is called when the component creates a new OpenGL context. | |
| virtual void | releaseOpenGLContext () |
| This method is called when the component shuts down its OpenGL context. | |
| OpenGLContext * | getCurrentContext () const noexcept |
| Returns the context that will draw into this component. | |
| bool | makeCurrentContextActive () |
| Makes this component the current openGL context. | |
| void | makeCurrentContextInactive () |
| Stops the current component being the active OpenGL context. | |
| bool | isActiveContext () const noexcept |
| Returns true if this component's context is the active openGL context for the current thread. | |
| virtual bool | renderAndSwapBuffers () |
| Calls the rendering callback, and swaps the buffers afterwards. | |
| CriticalSection & | getContextLock () noexcept |
| This returns a critical section that can be used to lock the current context. | |
| void | deleteContext () |
| Delete the context. | |
| void * | getNativeWindowHandle () const |
| Returns the native handle of an embedded heavyweight window, if there is one. | |
Protected Member Functions | |
| virtual void | startRenderThread () |
| Kicks off a thread to start rendering. | |
| virtual void | stopRenderThread () |
| Cleans up the rendering thread. | |
| void | paint (Graphics &g) |
| Components can override this method to draw their content. | |
A component that contains an OpenGL canvas.
Override this, add it to whatever component you want to, and use the renderOpenGL() method to draw its contents.
| OpenGLComponent::OpenGLComponent | ( | OpenGLType | type = openGLDefault, |
| bool | useBackgroundThread = false |
||
| ) |
Creates an OpenGLComponent.
If useBackgroundThread is true, the component will launch a background thread to do the rendering. If false, then renderOpenGL() will be called as part of the normal paint() method.
| OpenGLComponent::~OpenGLComponent | ( | ) |
Destructor.
| void OpenGLComponent::setPixelFormat | ( | const OpenGLPixelFormat & | formatToUse ) |
Changes the pixel format used by this component.
| const OpenGLPixelFormat OpenGLComponent::getPixelFormat | ( | ) | const |
Returns the pixel format that this component is currently using.
| void OpenGLComponent::shareWith | ( | OpenGLContext * | contextToShareListsWith ) |
Specifies an OpenGL context which should be shared with the one that this component is using.
This is an OpenGL feature that lets two contexts share their texture data.
Note that this pointer is stored by the component, and when the component needs to recreate its internal context for some reason, the same context will be used again to share lists. So if you pass a context in here, don't delete the context while this component is still using it! You can call shareWith (nullptr) to stop this component from sharing with it.
| OpenGLContext* OpenGLComponent::getShareContext | ( | ) | const |
Returns the context that this component is sharing with.
| void OpenGLComponent::swapBuffers | ( | ) |
Flips the openGL buffers over.
| bool OpenGLComponent::isUsingDedicatedThread | ( | ) | const |
Returns true if the component is performing the rendering on a background thread.
This property is specified in the constructor.
| virtual void OpenGLComponent::renderOpenGL | ( | ) | [pure virtual] |
This replaces the normal paint() callback - use it to draw your openGL stuff.
When this is called, makeCurrentContextActive() will already have been called for you, so you just need to draw.
| virtual void OpenGLComponent::newOpenGLContextCreated | ( | ) | [pure virtual] |
This method is called when the component creates a new OpenGL context.
A new context may be created when the component is first used, or when it is moved to a different window, or when the window is hidden and re-shown, etc.
You can use this callback as an opportunity to set up things like textures that your context needs.
New contexts are created on-demand by the makeCurrentContextActive() method - so if the context is deleted, e.g. by changing the pixel format or window, no context will be created until the next call to makeCurrentContextActive(), which will synchronously create one and call this method. This means that if you're using a non-GUI thread for rendering, you can make sure this method is be called by your renderer thread.
When this callback happens, the context will already have been made current using the makeCurrentContextActive() method, so there's no need to call it again in your code.
| virtual void OpenGLComponent::releaseOpenGLContext | ( | ) | [virtual] |
This method is called when the component shuts down its OpenGL context.
You can use this callback to delete textures and any other OpenGL objects you created in the component's context. Be aware: if you are using a render thread, this may be called on the thread.
When this callback happens, the context will have been made current using the makeCurrentContextActive() method, so there's no need to call it again in your code.
| OpenGLContext* OpenGLComponent::getCurrentContext | ( | ) | const |
Returns the context that will draw into this component.
This may return 0 if the component is currently invisible or hasn't currently got a context. The context object can be deleted and a new one created during the lifetime of this component, and there may be times when it doesn't have one.
| bool OpenGLComponent::makeCurrentContextActive | ( | ) |
Makes this component the current openGL context.
You might want to use this in things like your resize() method, before calling GL commands.
If this returns false, then the context isn't active, so you should avoid making any calls.
This call may actually create a context if one isn't currently initialised. If it does this, it will also synchronously call the newOpenGLContextCreated() method to let you initialise it as necessary.
| void OpenGLComponent::makeCurrentContextInactive | ( | ) |
Stops the current component being the active OpenGL context.
This is the opposite of makeCurrentContextActive()
| bool OpenGLComponent::isActiveContext | ( | ) | const |
Returns true if this component's context is the active openGL context for the current thread.
| virtual bool OpenGLComponent::renderAndSwapBuffers | ( | ) | [virtual] |
Calls the rendering callback, and swaps the buffers afterwards.
This is called automatically by paint() when the component needs to be rendered. Returns true if the operation succeeded.
| CriticalSection& OpenGLComponent::getContextLock | ( | ) |
This returns a critical section that can be used to lock the current context.
Because the context that is used by this component can change, e.g. when the component is shown or hidden, then if you're rendering to it on a background thread, this allows you to lock the context for the duration of your rendering routine.
| void OpenGLComponent::deleteContext | ( | ) |
Delete the context.
You should only need to call this if you've written a custom thread - if so, make sure that your thread calls this before it terminates.
| void* OpenGLComponent::getNativeWindowHandle | ( | ) | const |
Returns the native handle of an embedded heavyweight window, if there is one.
E.g. On windows, this will return the HWND of the sub-window containing the opengl context, on the mac it'll be the NSOpenGLView.
| virtual void OpenGLComponent::startRenderThread | ( | ) | [protected, virtual] |
Kicks off a thread to start rendering.
The default implementation creates and manages an internal thread that tries to render at around 50fps, but this can be overloaded to create a custom thread.
| virtual void OpenGLComponent::stopRenderThread | ( | ) | [protected, virtual] |
Cleans up the rendering thread.
Used to shut down the thread that was started by startRenderThread(). If you've created a custom thread, then you should overload this to clean it up and delete it.
| void OpenGLComponent::paint | ( | Graphics & | g ) | [protected, virtual] |
Components can override this method to draw their content.
The paint() method gets called when a region of a component needs redrawing, either because the component's repaint() method has been called, or because something has happened on the screen that means a section of a window needs to be redrawn.
Any child components will draw themselves over whatever this method draws. If you need to paint over the top of your child components, you can also implement the paintOverChildren() method to do this.
If you want to cause a component to redraw itself, this is done asynchronously - calling the repaint() method marks a region of the component as "dirty", and the paint() method will automatically be called sometime later, by the message thread, to paint any bits that need refreshing. In Juce (and almost all modern UI frameworks), you never redraw something synchronously.
You should never need to call this method directly - to take a snapshot of the component you could use createComponentSnapshot() or paintEntireComponent().
| g | the graphics context that must be used to do the drawing operations. |
Reimplemented from Component.
