// Copyright (C) 2015 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\example video/qmlvideo
\title QML Video Example
\ingroup multimedia_examples
\examplecategory {Multimedia}
\brief Transforming video and camera viewfinder content.

\e{QML Video} demonstrates the various transformations (move; resize; rotate;
change aspect ratio) that can be applied to QML \l VideoOutput and \l Camera
types.

It also shows how native code can be combined with QML to implement more
advanced functionality - in this case, C++ code is used to calculate the QML
frame rate.  This value is rendered in QML in a semi-transparent item
overlaid on the video content.

The following image shows the application executing the video-overlay scene,
which creates a dummy overlay item (just a semi-transparent \l{Rectangle}),
which moves across the \l{VideoOutput} item.

\image qmlvideo-overlay.jpg

\include examples-run.qdocinc

\section1 Application Structure

The \c Main.qml file creates a UI which includes the following items:

\list
    \li Two \c Button instances, each of which displays a filename, and can be
        used to launch a \c FileDialog.
    \li An exit \c Button.
    \li A \c SceneSelectionPanel, which is a flickable list displaying the
        available scenes.
    \li At the lower left, an item which displays the QML repainting rate - the
       upper number is the instantaneous frame rate and the lower number is the
       average over the past second.
\endlist

\image qmlvideo-menu.jpg

Each scene in the flickable list is implemented in its own QML file - for
example the video-basic scene (which just displays a static \l{VideoOutput}
in the center of the screen) is implemented in the \c VideoBasic.qml file.  As
you can see from the code, this makes use of a type of inheritance; a
\c VideoBasic item ...

\quotefromfile video/qmlvideo/qmlvideo/VideoBasic.qml
\skipto SceneBasic
\printuntil /^\}/

... is of type \c SceneBasic ...

\quotefromfile video/qmlvideo/qmlvideo/SceneBasic.qml
\skipto import
\printuntil contentType
\dots
\skipto Content
\printuntil content
\dots
\skipto }
\printuntil /^\}/

... which itself is a \c Scene:

\quotefromfile video/qmlvideo/qmlvideo/Scene.qml
\skipto import
\printuntil root
\dots
\skipto property QtObject content
\printuntil content
\dots
\skipto Button
\printuntil /^\}/

\c SceneBasic describes the structure and behavior of the scene, but is
agnostic of the type of content which will be displayed - this is abstracted
by \c Content.

This pattern allows us to define a particular use case (in this case, simply
display a static piece of content), and then instantiate that use case for
both video content (\c {VideoBasic}) and camera content \c ({CameraBasic}).
This approach is used to implement many of the other scenes - for example,
\e {"repeatedly slide the content from left to right and back again"} is
implemented by \c SceneMove, on which \c VideoMove and \c CameraMove are based.

Depending on the value of the contentType property in the top-level scene
instance, the embedded \c Content item creates either a
\l[QML]{MediaPlayer} or a \l[QML]{Camera} item.

\section1 Calculating and Displaying QML Painting Rate

The QML painting rate is calculated by the FrequencyMonitor class, which
turns a stream of events (received via the notify() slot), into an
instantaneous and an averaged frequency:

\quotefromfile video/qmlvideo/frequencymonitor/frequencymonitor.h
\skipto class FrequencyMonitor : public QObject
\printuntil QML_ELEMENT
\skipto Q_PROPERTY(qreal instantaneousFrequency
\printuntil averageFrequencyChanged)
\dots
\skipto public slots
\printuntil notify();
\skipto };
\printline };

The FrequencyMonitor class is exposed to QML by adding the macro QML_ELEMENT to the
class declaration as shown above, and its data is displayed by defining a QML item
called FrequencyItem, like this:

\quotefromfile video/qmlvideo/frequencymonitor/FrequencyItem.qml
\skipto import frequencymonitor
\printuntil id: root
\dots
\skipto function notify
\printuntil id: monitor
\skipto onAverageFrequencyChanged
\printuntil {
\skipto averageFrequencyText
\printuntil /^\}/

The result looks like this:

\image video-qml-paint-rate.png

All that remains is to connect the afterRendering() signal of the QQuickView
object to a JavaScript function, which will eventually call
\c frequencyItem.notify():

\quotefromfile video/qmlvideo/main.cpp
\skipto int main(
\printuntil ;
\dots
\skipto QQuickView
\printuntil ;
\dots
\skipto QQuickItem
\printuntil ;
\dots
\skipto QObject::connect
\printuntil SLOT(qmlFramePainted()));

*/
