Canvas that provides a 3D rendering context. More...
Import Statement: | import QtCanvas3D 1.1 |
Since: | QtCanvas3D 1.0 |
The Canvas3D is a QML element that, when placed in your Qt Quick 2 scene, allows you to get a 3D rendering context and call 3D rendering API calls through that context object. Use of the rendering API requires knowledge of OpenGL-like rendering APIs.
There are two functions that are called by the Canvas3D implementation:
See also Context3D.
context : Context3D |
This property can be used to access the context created with getContext() method.
See also getContext().
Specifies the ratio between logical pixels (used by the Qt Quick) and actual physical on-screen pixels (used by the 3D rendering).
fps : int |
This property specifies the current number of frames rendered per second. The value is recalculated every 500 ms, as long as any rendering is done.
Note: This property only gets updated after a Canvas3D frame is rendered, so if no frames are being drawn, this property value won't change. It is also based on the
number of Canvas3D frames actually rendered since the value was last updated, so it may not accurately reflect the actual rendering performance when If Canvas3D.renderOnDemand property is true
.
See also frameTimeMs.
pixelSize : size |
Specifies the size of the render target surface in physical on-screen pixels used by the 3D rendering.
renderOnDemand : bool |
If the value is false
, the render loop runs constantly and Canvas3D.paintGL() signal is emitted once per frame. If the value is true
,
Canvas3D.paintGL() is only emitted when Canvas3D content needs to be re-rendered because a geometry change or some
other event affecting the Canvas3D content occurred. The application can also request a render using Canvas3D.requestRender() method.
Specifies how the rendering should be done.
Canvas3D.RenderTargetOffscreenBuffer
indicates rendering is done into an offscreen buffer and the finished texture is used for the Canvas3D item. This is the
default target.
Canvas3D.RenderTargetBackground
indicates the rendering is done to the background of the Qt Quick scene, in response to QQuickWindow::beforeRendering()
signal.
Canvas3D.RenderTargetForeground
indicates the rendering is done to the foreground of the Qt Quick scene, in response to QQuickWindow::afterRendering()
signal.
Canvas3D.RenderTargetBackground
and Canvas3D.RenderTargetForeground
targets render directly to the same framebuffer the rest of the Qt Quick scene uses. This will improve performance on platforms
that are fill-rate limited, but using these targets imposes several limitations on the usage of Canvas3D:
Canvas3D.RenderTargetOffscreenBuffer
render target.
main.cpp
.This property can only be modified before the Canvas3D item has been rendered for the first time.
Emitted when OpenGL context is lost. This happens whenever the parent window of the Canvas3D is destroyed (or otherwise loses its context), or Canvas3D is moved to a different window. Removing Canvas3D from a window and adding it back to the same window doesn't cause context loss, as long as the window itself stays alive.
When context is lost, all objects created by Context3D are invalidated.
See also contextRestored.
Emitted when OpenGL context is restored after a loss of context occurred. The Context3D attached to the canvas needs to be reinitialized, so initializeGL is also emitted after this signal.
See also contextLost.
Emitted once when Canvas3D is ready and OpenGL state initialization can be done by the client.
Emitted each time a new frame should be drawn to Canvas3D. Driven by the Qt Quick scenegraph loop.
int frameSetupTimeMs() |
This method returns the number of milliseconds Canvas3D took to process the PaintGL signal for the previous frame. Before any frames have been rendered this method returns 0. This time doesn't include time spent on actual OpenGL rendering of the frame, nor the time the scene graph takes to present the frame to the screen. This value is updated after PaintGL signal handler returns.
This QML method was introduced in QtCanvas3D 1.1.
See also fps and frameTimeMs.
int frameTimeMs() |
This method returns the number of milliseconds the renderer took to process the OpenGL portion of the rendering for the previous frame. Before any frames have been rendered this method returns 0. This time is measured from the point OpenGL commands are transferred to render thread to the time glFinish() returns, so it doesn't include the time spent parsing JavaScript, nor the time the scene graph takes to present the frame to the screen. This value is updated for the previous frame when the next frame OpenGL command transfer is done.
See also fps and frameSetupTimeMs.
Context3D getContext(string type, Canvas3DContextAttributes options) |
Returns the 3D rendering context that allows 3D rendering calls to be made. The type parameter is ignored for now, but a string is expected to be given. If Canvas3D.renderTarget property value is either Canvas3D.RenderTargetBackground
or
Canvas3D.RenderTargetForeground
, the options parameter is also ignored, the context attributes of the Qt Quick context are used, and the Canvas3DContextAttributes.preserveDrawingBuffer property is forced to false
. The options parameter is only parsed when the
first call to getContext() is made and is ignored in subsequent calls if given. If the first call is made without giving the options parameter, then the
context and render target is initialized with default configuration.
See also Canvas3DContextAttributes, Context3D, and renderTarget.
Returns the 3D rendering context that allows 3D rendering calls to be made. The type parameter is ignored for now, but a string is expected to be given.
Queues a new frame for rendering when Canvas3D.renderOnDemand property is true
. Does nothing when Canvas3D.renderOnDemand property is false
.