Q3DSSurfaceViewer Class | OpenGL Runtime 2.8.0

- OpenGL Runtime
- OpenGL Runtime
- C++ Classes
- Q3DSSurfaceViewer
- Qt 3D Studio OpenGL Runtime 2.8 Manual

# Q3DSSurfaceViewer Class

Renders a Qt 3D Studio presentation on a QWindow or an offscreen render target using OpenGL. More...

Header: | #include <Q3DSSurfaceViewer>
Since: | Qt 3D Studio 2.0
Inherits: | QObject

- List of all members, including inherited members
- Obsolete members

## Properties

- autoSize : bool
- error : const QString
- presentationId : const QString

- running : const bool
- size : QSize
- updateInterval : int

- 1 property inherited from QObject

## Public Functions

| Q3DSSurfaceViewer(QObject *parent = nullptr)
virtual | ~Q3DSSurfaceViewer()
bool | autoSize() const
QOpenGLContext * | context() const
bool | create(QSurface *surface, QOpenGLContext *context)
bool | create(QSurface *surface, QOpenGLContext *context, GLuint fboId)
void | destroy()
QString | error() const
int | fboId() const
QImage | grab(const QRect &rect = QRect())
bool | isRunning() const
Q3DSPresentation * | presentation() const
QString | presentationId() const
QQmlEngine * | qmlEngine() const
void | setAutoSize(bool autoSize)
void | setQmlEngine(QQmlEngine *qmlEngine)
void | setSize(const QSize &size)
void | setUpdateInterval(int interval)
Q3DSViewerSettings * | settings() const
QSize | size() const
QSurface * | surface() const
int | updateInterval() const

- 31 public functions inherited from QObject

## Public Slots

void | update()

- 1 public slot inherited from QObject

## Signals

void | afterRendering()
void | autoSizeChanged(bool autoSize)
void | errorChanged()
void | frameUpdate()
void | presentationIdChanged(const QString &id)
void | presentationLoaded()
void | presentationReady()
void | runningChanged(bool initialized)
void | sizeChanged(const QSize &size)
void | updateIntervalChanged(bool autoUpdate)

- 2 signals inherited from QObject

## Static Public Members

const QMetaObject | staticMetaObject

- 9 static public members inherited from QObject

### Additional Inherited Members

- 9 protected functions inherited from QObject

## Detailed Description

Renders a Qt 3D Studio presentation on a QWindow or an offscreen render target using OpenGL.

Q3DSSurfaceViewer is used to render Qt 3D Studio presentations onto a QSurface. In practice this means two types of uses: rendering to an on-screen QWindow, or rendering to an offscreen render target (typically an OpenGL texture via a framebuffer object and a QOffscreenSurface).

#### Example Usage

     int main(int argc, char *argv[])
     {
         QGuiApplication app(argc, argv);

         QOpenGLContext context;
         context.create();

         QWindow window;
         window.setSurfaceType(QSurface::OpenGLSurface);
         window.setFormat(context.format());
         window.create();

         Q3DSSurfaceViewer viewer;
         viewer.presentation()->setSource(QUrl(QStringLiteral("qrc:/my_presentation.uip")));
         viewer.setUpdateInterval(0); // enable automatic updates

         // Register a scene object for slide management (optional)
         Q3DSSceneElement scene(viewer.presentation(), QStringLiteral("Scene"));

         // Register an element object for attribute setting (optional)
         Q3DSElement element(viewer.presentation(), QStringLiteral("Scene.Layer.myCarModel"));

         viewer.create(&window, &context);

         w.resize(1024, 768);
         w.show();

         return app.exec();
     }

## Property Documentation

### autoSize : bool

Specifies whether the viewer should change the size of the presentation automatically to match the surface size when surface size changes. The size property is updated automatically whenever the viewer is updated if this property value is `true`.

When rendering offscreen, via a QOffscreenSurface, this property must be set to `false` by the application since it is then up to the application to provide a QOpenGLFramebufferObject with the desired size. The size of the Q3DSSurfaceViewer must be set to the same value.

The default value is `true`.

Access functions:

bool | autoSize() const
void | setAutoSize(bool autoSize)

Notifier signal:

void | autoSizeChanged(bool autoSize)

### error : const QString

Error string.

This property is read-only.

Access functions:

QString | error() const

Notifier signal:

void | errorChanged()

### presentationId : const QString

Access functions:

QString | presentationId() const

Notifier signal:

void | presentationIdChanged(const QString &id)

### running : const bool

The value of this property is `true` when the presentation has been loaded and is ready to be shown.

This property is read-only.

Access functions:

bool | isRunning() const

Notifier signal:

void | runningChanged(bool initialized)

### size : QSize

Holds the desired size of the presentation. Relevant only when autoSize is set to `false`.

Access functions:

QSize | size() const
void | setSize(const QSize &size)

Notifier signal:

void | sizeChanged(const QSize &size)

See also autoSize.

### updateInterval : int

Holds the viewer update interval in milliseconds. If the value is negative, the viewer doesn't update the presentation automatically.

The default value is -1, meaning there are no automatic updates and update() must be called manually.

Access functions:

int | updateInterval() const
void | setUpdateInterval(int interval)

Notifier signal:

void | updateIntervalChanged(bool autoUpdate)

See also update().

## Member Function Documentation

### Q3DSSurfaceViewer::Q3DSSurfaceViewer(QObject *parent = nullptr)

Q3DSSurfaceViewer::Q3DSSurfaceViewer Constructor. parent Optional parent of the object.

### `[virtual]` Q3DSSurfaceViewer::~Q3DSSurfaceViewer()

Q3DSSurfaceViewer::~Q3DSSurfaceViewer Destructor

### `[signal]` void Q3DSSurfaceViewer::afterRendering()

Emitted when a frame has been rendered.

### QOpenGLContext *Q3DSSurfaceViewer::context() const

Returns the context given in initialization.

See also create().

### bool Q3DSSurfaceViewer::create(QSurface *surface, QOpenGLContext *context)

Initializes Q3DSSurfaceViewer to render the presentation to the given surface using the context.

The source property of the attached presentation must be set before the viewer can be initialized.

Returns whether the initialization succeeded.

See also running, Q3DSPresentation::source, and presentation().

### bool Q3DSSurfaceViewer::create(QSurface *surface, QOpenGLContext *context, GLuint fboId)

Initializes Q3DSSurfaceViewer to render the presentation to the given surface using the context and optional framebuffer id (fboId). If fboId is omitted, it defaults to zero.

The source property of the attached presentation must be set before the viewer can be initialized.

Returns whether the initialization succeeded.

See also running, Q3DSPresentation::source, and presentation().

### void Q3DSSurfaceViewer::destroy()

Releases the presentation and all related resources. The Q3DSSurfaceViewer instance can be reused by calling create() again.

### QString Q3DSSurfaceViewer::error() const

Returns the error string.

Note: Getter function for property error.

### int Q3DSSurfaceViewer::fboId() const

Returns the framebuffer id given in initialization.

See also create().

### `[signal]` void Q3DSSurfaceViewer::frameUpdate()

Emitted each time a frame has been rendered.

### QImage Q3DSSurfaceViewer::grab(const QRect &rect = QRect())

Grabs the data rendered to the framebuffer into an image using the given rect. The rect parameter is optional. If it is omitted, the whole framebuffer is captured.

Note: This is a potentially expensive operation.

### Q3DSPresentation *Q3DSSurfaceViewer::presentation() const

Returns the presentation object used by the Q3DSSurfaceViewer.

### `[signal]` void Q3DSSurfaceViewer::presentationLoaded()

Emitted when the presentation has been loaded and is ready to be shown.

### `[signal]` void Q3DSSurfaceViewer::presentationReady()

Emitted when first frame is about to be shown. DataInputs and setAttribute are ready to be used after this signal.

### QQmlEngine *Q3DSSurfaceViewer::qmlEngine() const

Returns the QML engine set with setQmlEngine method.

See also setQmlEngine.

### void Q3DSSurfaceViewer::setQmlEngine(QQmlEngine *qmlEngine)

Sets the QML engine for rendering QML streams of the presentation to qmlEngine. The QML engine must be set before Q3DSSurfaceViewer::create is called. If the QML engine is not set, a new one will be created during runtime initialization.

See also qmlEngine.

### Q3DSViewerSettings *Q3DSSurfaceViewer::settings() const

Returns the settings object used by the Q3DSSurfaceViewer.

### QSurface *Q3DSSurfaceViewer::surface() const

Returns the surface given in initialization.

See also create().

### `[slot]` void Q3DSSurfaceViewer::update()

Updates the surface viewer with a new frame.