diff options
17 files changed, 593 insertions, 295 deletions
diff --git a/src/multimedia/doc/qtmultimedia.qdocconf b/src/multimedia/doc/qtmultimedia.qdocconf index dfafd8715..260e62b89 100644 --- a/src/multimedia/doc/qtmultimedia.qdocconf +++ b/src/multimedia/doc/qtmultimedia.qdocconf @@ -6,7 +6,7 @@ description = Qt Multimedia Documentation version = $QT_VERSION moduleheader = QtMultimediaDoc -includepaths = -I . +includepaths = . # The following parameters are for creating a qhp file, the qhelpgenerator # program can convert the qhp file into a qch file which can be opened in diff --git a/src/multimedia/doc/src/audiooverview.qdoc b/src/multimedia/doc/src/audiooverview.qdoc index ce49e1e98..bfff29689 100644 --- a/src/multimedia/doc/src/audiooverview.qdoc +++ b/src/multimedia/doc/src/audiooverview.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the Qt for Multimedia module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,13 +14,25 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ @@ -28,52 +40,64 @@ /*! \page audiooverview.html \title Audio Overview -\brief Audio playback, recording and processing +\inlineimage sound-wave-small.jpg +\brief Playback, recording and processing of Audio. \section1 Audio Features -Qt Multimedia offers a range of audio classes, covering both low and -high level approaches to audio input, output and processing. +Qt Multimedia offers a range of audio classes that cover both low and +high level approaches to: audio input, output and processing. \section1 Audio Implementation Details \section2 Playing Compressed Audio -For playing media or audio files that are not simple, uncompressed audio, you can -use the \l QMediaPlayer C++ class, or the \l {MediaPlayer} QML type. +For playing media or audio files that are not simple, uncompressed audio, you +can use the QMediaPlayer C++ class, or the \l{MediaPlayer} QML type. The QMediaPlayer class and associated QML types are also capable of playing -\l{multimedia-playing-video}{video}, if required. The compressed audio formats supported does depend -on the operating system environment, and also what decoder plugins the user -may have installed. +\l{multimedia-playing-video}{video}, if required. The compressed audio formats +supported depends on: +\list + \li The operating system environment. + \li Any decoder plugins the user may have installed. +\endlist Here is how you play a local file using C++: \snippet multimedia-snippets/media.cpp Local playback -You can also put files (even remote URLs) into a playlist: +You can also put files, and remote URLs into a playlist: \snippet multimedia-snippets/media.cpp Audio playlist \section2 Recording Audio to a File -For recording audio to a file, the \l {QMediaRecorder} class allows you +For recording audio to a file, the QMediaRecorder class allows you to compress audio data from an input device and record it. \snippet multimedia-snippets/media.cpp Audio recorder -\l {QMediaCaptureSession} provides support for more complex capturing and recording use cases. +QMediaCaptureSession provides support for more complex use cases involving the +capturing and recording of audio. \section2 Low Latency Sound Effects -In addition to the raw access to sound devices described above, the QSoundEffect class (and -\l {SoundEffect} QML type) offers a slightly higher level way to play -sounds. This class allows you to specify a WAV format file which can +In addition to \l{raw access} to sound devices, the QSoundEffect +class (and \l{SoundEffect} QML type) offers a more abstract way to play +sounds. This class allows you to specify a \b{WAV format} file, which can then be played with low latency when necessary. -You can adjust the number of \l {QSoundEffect::loopCount()}{loops} a sound effect is played, as well as -the \l {QSoundEffect::setVolume()}{volume} (or \l {QSoundEffect::setMuted()}{muting}) of the effect. +You can adjust the: +\list + \li \l{QSoundEffect::loopCount()}{Number of loops} in which a sound effect + is played. + \li \l{QSoundEffect::setVolume()}{Volume} of the sound effect. + \li \l{QSoundEffect::setMuted()}{Muting} of the sound effect. +\endlist +\target raw access \section2 Low Level Audio Playback and Recording + Qt Multimedia offers classes for raw access to audio input and output facilities, allowing applications to receive raw data from devices like -microphones, and to write raw data to speakers or other devices. Generally +microphones, and to write raw data to speakers or other devices. Generally these classes do not do any audio decoding, or other processing, but they can support different types of raw audio data. @@ -90,13 +114,14 @@ for \c pull mode with QAudioSource, when audio data is available then the data will be written directly to the QIODevice. In \c push mode, the audio device provides a QIODevice instance that -can be written or read to as needed. Typically this results in simpler +can be written or read to as needed. Typically, this results in simpler code but more buffering, which may affect latency. \section2 Decoding Compressed Audio to Memory + In some cases you may want to decode a compressed audio file and do further -processing yourself (for example, mixing multiple samples or using custom -digital signal processing algorithms). QAudioDecoder supports decoding local +processing yourself. For example, mixing multiple samples or using custom +digital signal processing algorithms. QAudioDecoder supports decoding local files or data streams from QIODevice instances. Here's an example of decoding a local file: @@ -122,3 +147,4 @@ There are both C++ and QML examples available. \annotatedlist multimedia_audio_qml */ + diff --git a/src/multimedia/doc/src/cameraoverview.qdoc b/src/multimedia/doc/src/cameraoverview.qdoc index 09c7f3632..30f74a4e4 100644 --- a/src/multimedia/doc/src/cameraoverview.qdoc +++ b/src/multimedia/doc/src/cameraoverview.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the Qt for Multimedia module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,13 +14,25 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ @@ -31,52 +43,75 @@ \brief Camera viewfinder, still image capture, and video recording. The Qt Multimedia API provides a number of camera related classes, so you -can access images and videos from mobile device cameras or webcameras. +can access images and videos from mobile device cameras or web cameras. There are both C++ and QML APIs for common tasks. \section1 Camera Features -In order to use the camera classes a quick overview of the way a camera -works is needed. If you're already familiar with this, you can skip ahead to +In order to use the camera classes, a quick overview of the way a camera +works is needed. If you're already familiar with this, you can skip ahead to \l {camera-tldr}{Camera implementation details}. +For a more detailed explanations of how a camera works, see the following YouTube +clip. + +\youtube qS1FmgPVLqw \section2 The Lens Assembly + At one end of the camera assembly is the lens assembly (one or -more lenses, arranged to focus light onto the sensor). The lenses -themselves can sometimes be moved to adjust things like focus and zoom, -or they might be fixed in an arrangement to give a good balance between -objects in focus, and cost. +more lenses, arranged to focus light onto the sensor). The lenses +themselves can sometimes be moved to adjust things like focus and zoom. They +might also be fixed in an arrangement for a good balance between maintaining +focus and cost. + +\image how-focus-works.gif "An animation of how focus works" + +\image Zoom.gif "An animation of how zoom works." Some lens assemblies can automatically be adjusted so that an object at different distances from the camera can be kept in focus. This is usually done by measuring how sharp a particular area of the -frame is, and by adjusting the lens assembly until it is maximally -sharp. In some cases the camera will always use the center of the -frame for this. Other cameras may also allow the region to focus -to be specified (for "touch to zoom", or "face zoom" features). +frame is, and then adjusting the lens assembly to find the peak sharpness. In +some cases, the camera will always use the center of the frame for this. +In other cases, a camera may also allow this target focus region to be specified. +Some examples of this feature include: +\list +\li Face zoom: Using computer vision to detect and use one or more faces as the +target. +\li Touch to zoom: Enabling the user to manually select an area via the preview +screen. +\endlist \section2 The Sensor Once light arrives at the sensor, it gets converted into digital pixels. This process can depend on a number of things but ultimately comes down -to two things - how long the conversion is allowed to take, and how -bright the light is. The longer a conversion can take, the better the -quality. Using a flash can assist with letting more light hit the sensor, +to two things: +\list +\li The length of time conversion is allowed to take. Also known as exposure +time. +\li How bright the light is. +\endlist + +The longer a conversion is allowed to take, the better the resulting image +quality. Using a flash can assist with letting more light hit the sensor, allowing it to convert pixels faster, giving better quality for the same -amount of time. Conversely, allowing a longer conversion time can let you -take photos in darker environments, as long as the camera is steady. +amount of time. Conversely, allowing a longer conversion time can let you +take photos in darker environments, \b{as long as the camera is steady}. If the +camera moves while the sensor is recording, the resulting image is blurred. \section2 Image Processing After the image has been captured by the sensor, the camera firmware performs various image processing tasks on it to compensate for various sensor -characteristics, current lighting, and desired image properties. Faster sensor -pixel conversion times tend to introduce digital noise, so some amount of image -processing can be done to remove this based on the camera sensor settings. +characteristics, current lighting, and desired image properties. Faster sensor +pixel conversion times may introduce digital noise, so some amount of image +processing can be done to remove this, based on the camera sensor settings. The color of the image can also be adjusted at this stage to compensate for different light sources - fluorescent lights and sunlight give very different appearances to the same object, so the image can be adjusted based on the white balance of the picture (due to the different color temperatures of the light sources). +\image image_processing.png "5 examples of various image processing techniques." Some forms of "special effects" can also be performed at this stage. Black and white, sepia, or "negative" style images can be produced. @@ -84,21 +119,24 @@ and white, sepia, or "negative" style images can be produced. \section2 Recording for Posterity Finally, once a perfectly focused, exposed and processed image has been created, it can be put to good use. Camera images can be further processed -by application code (for example, to detect barcodes, or to stitch together a +by application code (for example, to detect bar-codes, or to stitch together a panoramic image), or saved to a common format like JPEG, or used to create a movie. Many of these tasks have classes to assist them. \target camera-tldr \section1 Camera Implementation Details -\section2 Detecting and Selecting Camera +\section2 Detecting and Selecting a Camera + +Before using the camera APIs, you should check that a camera is available at +runtime. If there is none available, you could disable camera related features +in your application. To perform this check in C++, use the +\l QCameraDevice::availableCameras() function, as shown in the example below: -Before using the camera APIs, you should check that a camera is available at runtime. If there -is none, you could for example disable camera related features in your application. To perform this -check in C++, use the \l QCameraDevice::availableCameras() function, as shown in the example below: \snippet multimedia-snippets/camera.cpp Camera overview check -In QML, use the \l{QtMultimedia::MediaDevices::availableCameras}{MediaDevices.availableCameras} +In QML, use the +\l{QtMultimedia::MediaDevices::availableCameras}{MediaDevices.availableCameras} property: \qml @@ -107,8 +145,8 @@ Item { } \endqml -After determining whether a camera is available, access it using the \l QCamera class in C++ or -the \l Camera type in QML. +After determining whether a camera is available, access it using the +\l QCamera class in C++ or the \l Camera type in QML. When multiple cameras are available, you can specify which one to use. @@ -116,8 +154,10 @@ In C++: \snippet multimedia-snippets/camera.cpp Camera selection -In QML, you can set the \c Camera \l{Camera::cameraDevice}{cameraDevice} property. All available cameras can -be retrieved from \l{QtMultimedia::MediaDevices::availableCameras}{MediaDevices.availableCameras}: + +In QML, you can set the \c Camera \l{Camera::cameraDevice}{cameraDevice} property. +All available cameras can be retrieved from +\l{QtMultimedia::MediaDevices::availableCameras}{MediaDevices.availableCameras}: \qml Camera { @@ -125,8 +165,9 @@ Camera { } \endqml -You can also select the camera by its physical position on the system rather than by camera info. -This is useful on mobile devices, which often have a front-facing and a back-facing camera. +You can also select a camera by its physical position on the system rather than +by camera info. This is useful on mobile devices, which often have a +front-facing and a back-facing camera. In C++: @@ -140,20 +181,22 @@ Camera { } \endqml -If neither cameraDevice nor position is specified, the default camera will be used. On desktop -platforms, the default camera is set by the user in the system settings. On a mobile device, the -back-facing camera is usually the default camera. You can get information about the default camera -using \l QCameraDevice::defaultCamera() in C++ or + +If both QCameraDevice and position aren't specified, the default camera will be +used. On desktop platforms, the default camera is set by the user in the system +settings. On a mobile device, the back-facing camera is usually the default +camera. You can get information about the default camera using +\l QCameraInfo::defaultCamera() in C++ or \l{QtMultimedia::MediaDevices::defaultCamera}{MediaDevices.defaultCamera} in QML. \section2 Preview While not strictly necessary, it's often useful to be able to see -what the camera is pointing at. +what the camera is pointing at. This is known as a preview. Depending on whether you're using QML or C++, you can do this in multiple ways. -In QML, you can use \l Camera and \l VideoOutput together in a CaptureSession to show a -simple viewfinder: +In QML, you can use \l Camera and videoOutput together to monitor a +captureSession. \qml Item { @@ -177,27 +220,29 @@ is useful for QGraphicsView. \snippet multimedia-snippets/camera.cpp Camera overview viewfinder -For advanced usage (like processing preview frames as they come, to detect -objects or patterns), you can also use your own QVideoSink and set that as the videoOutput -for the QCamera object. In this case you will need to render the viewfinder image yourself -by processing the data received from the newVideoFrame() signal. +For advanced usage (like processing preview frames as they come, which enables +detection of objects or patterns), you can also use your own QVideoSink and set +that as the videoOutput for the QCamera object. In this case, you will need to +render the viewfinder image yourself by processing the data received from the +newVideoFrame() signal. \snippet multimedia-snippets/camera.cpp Camera overview surface -On mobile devices, the preview image might not always be in the orientation you would expect. -The camera sensors on these devices are often mounted in landscape while the natural -orientation of the screen is portrait. This results in the image appearing sideways or inverted -depending on the device orientation. In order to reflect on screen what the user actually sees, you -should make sure the viewfinder frames are always rotated to the correct orientation, taking into +On mobile devices, the preview image might not always be in the orientation you +would expect. The camera sensors on these devices are often mounted in landscape +while the natural orientation of the screen is portrait. This results in the +image appearing sideways or inverted depending on the device orientation. In +order to reflect on screen what the user actually sees, you should make sure +the viewfinder frames are always rotated to the correct orientation, taking into account the camera sensor orientation and the current display orientation. \snippet multimedia-snippets/camera.cpp Camera overview viewfinder orientation \section2 Still Images -After setting up a viewfinder and finding something photogenic, -to capture an image we need to initialize a new QImageCapture -object. All that is then needed is to start the camera and capture the image. +After setting up a viewfinder and finding something photogenic, to capture an +image we need to initialize a new QImageCapture object. All that is then +needed is to start the camera and capture the image. \snippet multimedia-snippets/camera.cpp Camera overview capture @@ -213,72 +258,73 @@ well as creating a viewfinder, we will also initialize a media recorder object. Signals from the \e mediaEncoder can be connected to slots to react to changes in the state of the encoding process or error events. Recording itself -starts with the \l {QMediaRecorder::record()}{record()} function of -mediaEncoder being called, this causes the signal \l -{QMediaRecorder::recorderStateChanged()}{recorderStateChanged()} to be emitted. The -recording process can be changed with the \l {QMediaRecorder::record()}{record()}, -\l {QMediaRecorder::stop()}{stop()} slots in \l QMediaRecorder. - -On top of the above, QMediaRecorder provides a simple to use, but more limited all-in-one class -for recording audio and video content. +starts when the \l {QMediaEncoder::record()}{record()} function of mediaEncoder +is called. This causes the signal +\l{QMediaEncoder::stateChanged()}{stateChanged()} to be emitted. The +recording process can be changed with the \l {QMediaEncoder::record()}{record()} +, \l {QMediaEncoder::stop()}{stop()} slots in \l QMediaEncoder. \section2 Controlling the Imaging Pipeline -Now that the basics of capturing images or movies are covered, there are a number +Now that the basics of capturing images and movies are covered, there are a number of ways to control the imaging pipeline to implement some interesting techniques. As explained earlier, several physical and electronic elements combine to determine the final images, and you can control them with different classes. \section3 Focus and Zoom -QCamera allows the developer to set the general focus policy by means of the +QCamera allows you to set the general focus policy by means of the enums for the \l {QCamera::FocusMode}{FocusMode}. \l {QCamera::FocusMode}{FocusMode} deals with settings such as \l {QCamera::FocusModeAuto}, and \l {QCamera::FocusModeInfinity}. For camera hardware that supports it, \l QCamera::FocusModeAutoNear} allows -imaging of things that are close to the sensor. This is useful in applications like -barcode recognition, or business card scanning. +imaging of things that are close to the sensor. This is useful in applications +like bar-code recognition, or business card scanning. -In addition to focus, QCameraFocus allows you to control any available zoom using \l setZoomFactor() -or \l zoomTo(). The available zoom range might be limited (or fixed to unity), the allowed range can -be checked with \l minimumZoomFactor() and maximumZoomFactor(). +In addition to focus, QCameraFocus allows you to control any available zoom +functionality using \l setZoomFactor() or \l zoomTo(). The available zoom range +might be limited or entirely fixed to unity (1:1). The allowed range can +be checked with \l minimumZoomFactor() and \l maximumZoomFactor(). \section3 Exposure, Shutter Speed and Flash There are a number of settings that affect the amount of light that hits the camera sensor, and hence the quality of the resulting image. -The main settings for automatic image taking are the \l {QCamera::ExposureMode}{exposure mode} -and \l {QCamera::FlashMode}{flash mode}. Several other settings (ISO setting, - shutter speed) are usually managed automatically but can also be overridden if desired. +The main settings for automatic image taking are the +\l {QCamera::ExposureMode}{exposure mode} and \l {QCamera::FlashMode}{flash mode}. +Several other settings (such as: ISO setting and exposure time) are usually +managed automatically, but can also be overridden if desired. -Finally, you can control the flash hardware (if present) using this class. In some cases -the hardware may also double as a torch. +Finally, you can control the flash hardware (if present) using this class. In +some cases the hardware may also double as a torch. \target camera_image_processing \section3 Image Processing -The QCamera class lets you adjust the image processing -part of the pipeline. This includes the \l {QCamera::WhiteBalanceMode}{white balance} -(or color temperature), \l {QCamera::contrast()}{contrast}, and -\l {QCamera::saturation()}{saturation}. -Most cameras support automatic settings for all of these, so you shouldn't need to adjust them unless -the user wants a specific setting. +The QCamera class lets you adjust the image processing part of the pipeline. +These settings include: +\list + \li \l {QCamera::WhiteBalanceMode}{white balance} + (also known as color temperature) + \li \l {QCamera::contrast()}{contrast} + \li \l {QCamera::saturation()}{saturation} + \li \l {QCamera::hue()}{hue} + \li \l {QCamera::brightness()}{brightness} +\endlist -If you're taking a series of images (for example, to stitch them together for -a panoramic image), you should lock the image processing settings so that all the -images taken appear similar with \e {QCamera::searchAndLock(QCamera::LockWhiteBalance)}/ +Most cameras support automatic settings for all of these, so you shouldn't need +to adjust them unless the user wants a specific setting. \section3 Canceling Asynchronous Operations -Various operations such as image capture and auto focusing occur -asynchrously. These operations can often be canceled by the start of a new -operation as long as this is supported by the camera. For image capture, -the operation can be canceled by calling -\l {QImageCapture::cancelCapture()}{cancelCapture()}. For AutoFocus, -autoexposure or white balance cancellation can be done by calling -\e {QCamera::unlock(QCamera::LockFocus)}. +Various operations, such as image capture and auto focusing, occur asynchronously. +These operations can often be canceled by the start of a new operation, as long +as this is supported by the camera. For image capture, the operation can be +canceled by calling +\l {QImageCapture::cancelCapture()}{cancelCapture()}. + \section1 Examples diff --git a/src/multimedia/doc/src/changes.qdoc b/src/multimedia/doc/src/changes.qdoc index cab8c3b15..764e77738 100644 --- a/src/multimedia/doc/src/changes.qdoc +++ b/src/multimedia/doc/src/changes.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the Qt for Multimedia module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,13 +14,25 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ @@ -33,79 +45,85 @@ The Qt Multimedia module in Qt 6 replaces the Qt Multimedia module from Qt 5.x. -Existing code that uses Qt Multimedia from Qt 5 can be ported with limited effort. The -\l {changed features} section highlights changes relevant to porting. +Existing code that uses Qt Multimedia from Qt 5 can be ported with limited effort. +The \l {changed features} section highlights changes relevant to porting. -\section1 New features in Qt 6.0 +\section1 New features in Qt 6 There are a number of new features in Qt Multimedia: \list -\li QMediaCaptureSession class as the central object for media capture -\li Changed QMediaRecorder class to be a high level class for audio/video recording -\li new QMediaRecorder class to handle encoding of data produced in a capture session -\li Setting up the desired encodings when recording has changed significantly, see -QMediaEncoderSettings for details -\li Support for selection of audio, video and subtitle tracks when playing back media files -\li QAudioDecoder is now supported on all platforms + \li QMediaCaptureSession class is the central object for media capture. + \li Changed QMediaRecorder class to be a high level class for audio/video + recording. + \li new QMediaEncoder class to handle encoding of data produced in a capture + session. + \li Setting up the desired encoding when recording has changed significantly. + see QMediaEncoderSettings for details. + \li Support for selection of audio, video and subtitle tracks when playing + back media files has been added. + \li QAudioDecoder is now supported on all platforms. \endlist -\section1 Removed features +\section1 Removed Features \table 70% \header \li Removed feature - \li Notes + \li Notes or suggested alternative \row \li Playlist in QMediaPlayer - \li QMediaPlayer does not do any playlist handling anymore in Qt 6. The QMediaPlayList class - does however still exist and provides this functionality. Users will need to connect the - playlist to the mediaplayer themselves to handle playlists. + \li QMediaPlayer does not do any playlist handling anymore in Qt 6. + The QMediaPlayList class does however still exist and provides this + functionality. Users will need to connect the playlist to the mediaplayer + themselves to handle playlists. \row \li QAudioProbe and QVideoProbe - \li The audio and video probing API has been removed. A replacement API using custom audio - and video outputs may be added in a future release. + \li The audio and video probing API has been removed. \row \li QAudioRecorder and the Audio QML type - \li Use a QMediaCaptureSession or the CaptureSession QML type + \li Use a QMediaCaptureSession or the CaptureSession QML type. \row \li QMediaObject and QMediaBindableInterface - \li These classes have been removed in favor of a more direct API for setting up connections - between objects using e.g. setVideoOutput and QMediaCaptureSession. + \li These classes have been removed in favor of a more direct API for + setting up connections between objects using e.g. setVideoOutput and + QMediaCaptureSession. \row \li QCameraViewFinderSettings - \li This class has been removed. Use QCameraFormat to define the resolution and framerate the - camera should be using. + \li This class has been removed. Use QCameraFormat to define the + resolution and frame rate the camera should be using. \row \li QMediaContent - \li The class has been removed. Use QMediaPlayList for play lists and QUrl for individual - media files instead. + \li The class has been removed. Use QMediaPlayList for playlists and + QUrl for individual media files instead. \row \li QSound \li Use QSoundEffect instead. \row \li QVideoFilterRunnable - \li Use shader effects in QML instead or access the QVideoFrame's content in C++. + \li Use \l{shader effects} in QML instead or access the QVideoFrame's + content in C++. \row - \li Backend API - \li The backend API of Qt Multimedia is private in Qt 6. Having a public backend API was one - the main things that made supporting and enhancing Qt Multimedia in Qt 5 very difficult. - By making the backend API private, we expect to be able to better support new multimedia - use cases in the future. This includes all classes the contain "Control" or "Abstract" - in the class name in Qt 5. + \li Public back end API + \li The back end API of Qt Multimedia is private in Qt 6. This improves + response time for supporting new multimedia use cases. This includes all + classes that contain "Control" or "Abstract" in the class name in Qt 5. \row - \li Pluggable backends - \li Qt Multimedia in Qt 6 does not use a plugin infrastructure for its backends anymore. - This means that users do not need to ship those backends with their application anymore - neither. Instead the backend being used is determined at compile time based on the - underlying operating system. Qt uses gstreamer on Linux, WMF on Windows, AVFoundation - on macOS and iOS and the Android multimedia APIs on Android. + \li Back ends as plugins + \li Qt Multimedia in Qt 6 does not use a plugin infrastructure for its + back ends anymore. + This means that users no longer need to ship those back ends with their + application. Instead, the back end being used is determined at compile + time based on the underlying operating system. Qt uses \l gstreamer on + Linux, WMF on Windows, AVFoundation on macOS and iOS and the Android + multimedia APIs on Android. \endtable \section1 Changed features A number of classes previously offered in Qt Multimedia or Qt Multimedia Kit have -changed in ways that may affect previously written code. This table highlights such changes. +changed in ways that may affect previously written code. The following table +highlights these changes. \table 70% \header @@ -113,26 +131,31 @@ changed in ways that may affect previously written code. This table highlights s \li Notes \row \li Handling of Camera resolutions and frame rates - \li Handling of those has been simplified and a new QCameraFormat class helps selecting - the correct resolution and frame rate on the camera. + \li Handling of these has been simplified and a new QCameraFormat class + helps with selecting the correct resolution and frame rate for the camera. \row \li Video output handling on the C++ side has changed significantly. - \li QAbstractVideoSurface has been replaced by the QVideoSink class, and generic rendering - support has been enhanced to cover all pixel formats supported by Qt Multimedia + \li QAbstractVideoSurface has been replaced by the QVideoSink class, and + generic rendering support has been enhanced to cover all \l{pixel format}s + supported by Qt Multimedia. \row \li Metadata types - \li QMediaMetaData has changed significantly, mainly moving from string based - to enum based keys, and reducing the set of supported keys to the ones that - can be supported on most platforms. + \li QMediaMetaData has changed significantly: mainly moving from string + based to enum based keys, and reducing the set of supported keys to the + ones that can be supported on most platforms. \row \li QMediaFormat - \li Handling of formats for encoded media and the settings for the media recorder have - changed significantly. While Qt 5 provided a string based API and separated file format, - audio and video codecs into 3 classes, Qt 6 does unify the formats in the QMediaFormat class, - and other settings in QMediaRecorder. Setting up of file formats and codecs is now - enum based and doesn't use strings anymore. This puts some limitations on the set of codecs - that can be used, but helps provide a consistent cross-platform API and reduces the changes - for inconsistencies. + \li Handling of formats for encoded media and the settings for the media + encoder have changed significantly. Qt 5 provides a string based + API, a separated file format, and audio and video codecs into 3 classes. + However, Qt 6 unifies the formats in the QMediaFormat class, and encoder + settings in QMediaEncoderSettings. Setting up file formats and codecs + is now enum based and no longer uses strings. This puts some + limitations on the set of codecs that can be used, but helps provide a + consistent cross-platform API. + \row + \li QCameraImageCapture renamed QImageCapture + \li None \endtable */ diff --git a/src/multimedia/doc/src/images/Zoom.gif b/src/multimedia/doc/src/images/Zoom.gif Binary files differnew file mode 100644 index 000000000..dfba0faf1 --- /dev/null +++ b/src/multimedia/doc/src/images/Zoom.gif diff --git a/src/multimedia/doc/src/images/how-focus-works.gif b/src/multimedia/doc/src/images/how-focus-works.gif Binary files differnew file mode 100644 index 000000000..a691b49ac --- /dev/null +++ b/src/multimedia/doc/src/images/how-focus-works.gif diff --git a/src/multimedia/doc/src/images/image_processing.png b/src/multimedia/doc/src/images/image_processing.png Binary files differnew file mode 100644 index 000000000..2a52fbce3 --- /dev/null +++ b/src/multimedia/doc/src/images/image_processing.png diff --git a/src/multimedia/doc/src/images/noun_Media_166644.svg b/src/multimedia/doc/src/images/noun_Media_166644.svg new file mode 100644 index 000000000..cc2fa8d83 --- /dev/null +++ b/src/multimedia/doc/src/images/noun_Media_166644.svg @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + version="1.1" + x="0px" + y="0px" + viewBox="0 0 97.908676 59.1375" + enable-background="new 0 0 100 100" + xml:space="preserve" + id="svg26" + sodipodi:docname="noun_Media_166644.svg" + width="97.908676" + height="59.137501" + inkscape:version="1.0.2 (e86c870879, 2021-01-15, custom)"><metadata + id="metadata32"><rdf:RDF><cc:Work + rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs + id="defs30" /><sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="2560" + inkscape:window-height="1377" + id="namedview28" + showgrid="false" + inkscape:zoom="8.064" + inkscape:cx="32.007416" + inkscape:cy="20.413416" + inkscape:window-x="1912" + inkscape:window-y="-8" + inkscape:window-maximized="1" + inkscape:current-layer="svg26" + inkscape:document-rotation="0" /><g + transform="matrix(0.13985577,0,0,-0.1432582,-21.001292,1300.868)" + id="g20"><path + d="m 467.5,9080.3 c -2.1,-0.6 -3.7,-1.9 -4.6,-3.7 -0.7,-1.4 -0.8,-6.7 -0.8,-48.2 v -46.6 h 7.1 7.1 v 23.6 23.6 h 105.1 105.1 v -47.8 c 0,-26.2 0.1,-47.8 0.4,-47.8 0.2,0 3.2,0.6 6.7,1.4 l 6.4,1.3 0.1,69.7 c 0.1,68.3 0.1,69.7 -0.8,71.2 -0.5,0.9 -1.7,2 -2.6,2.5 -1.5,0.8 -6.9,0.9 -114.9,1 -62.1,0.2 -113.6,0 -114.3,-0.2 z m 32.5,-25.6 v -11.8 h -11.8 -11.8 v 11.8 11.8 h 11.8 11.8 z m 37.4,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 37.5,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 37.4,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 37.4,0 v -11.8 h -11.6 -11.6 v 11.8 11.8 h 11.6 11.6 z m 36.9,0 v -11.8 H 675.3 664 v 11.8 11.8 h 11.3 11.3 z" + id="path2" /><path + d="m 546,9008.9 c -1.2,-0.5 -2.5,-1.7 -3.1,-2.6 -1,-1.6 -1,-2.4 -1,-53.2 0,-46.4 0.1,-51.8 0.8,-53.3 1.1,-2.2 3.4,-3.6 6.2,-3.6 2,0 5.2,1.9 43.5,25.4 22.7,14 41.8,25.9 42.4,26.4 2.7,2.4 2.5,7.2 -0.2,9.8 -2.5,2.3 -83.1,51.5 -84.8,51.8 -1.2,0.2 -2.4,0 -3.8,-0.7 z m 41.8,-38.4 c 21.8,-13.4 28.3,-17.6 27.8,-18 -0.7,-0.7 -58.2,-36.1 -59.2,-36.5 -0.6,-0.2 -0.7,5.8 -0.7,37 v 37.3 l 1.9,-1.1 c 1,-0.7 14.6,-9.1 30.2,-18.7 z" + id="path4" /><path + d="m 179,8967.7 c -2.5,-0.4 -7.7,-2.3 -10.3,-3.6 -8.4,-4.4 -14.3,-11.9 -17.3,-21.7 l -1.1,-3.6 -0.1,-80.3 c -0.1,-54.6 0,-81.7 0.4,-84.8 1.8,-16.1 13.6,-28.6 29.5,-31.1 2.2,-0.4 49.5,-0.5 149.2,-0.5 120.1,0 146.6,0.1 149.7,0.7 10.8,2 20,8.9 24.9,18.7 3.9,7.9 3.6,2.1 3.6,93.6 0,90.9 0.2,85.5 -3.4,93 -4.6,9.6 -12.9,16.3 -23.3,19 -3.8,1 -5.4,1 -152.1,0.9 -81.8,-0.1 -149,-0.2 -149.7,-0.3 z m 297.5,-14 c 7.9,-1.7 14.6,-8.5 16.1,-16.7 0.7,-3.7 0.7,-159.8 0,-163.7 -1.4,-7.8 -7.3,-14.2 -14.8,-16.2 -2.9,-0.8 -13.8,-0.8 -150.6,-0.7 l -147.5,0.1 -3.3,1.6 c -4.4,2.1 -8.3,6 -10.3,10.3 l -1.6,3.3 -0.1,82.2 c -0.1,81.1 -0.1,82.3 0.9,85.5 2.2,7.1 9,13.2 16.2,14.4 0.7,0.1 66.8,0.2 146.8,0.3 104.9,0.1 146.3,0 148.2,-0.4 z" + id="path6" /><path + d="m 194,8929.6 c -0.8,-0.5 -1.9,-1.7 -2.3,-2.6 -0.8,-1.5 -0.9,-5.9 -0.9,-72.1 v -70.5 l 1.1,-1.7 c 0.7,-1 2,-2 3.4,-2.6 2.3,-1 2.3,-1 4.6,0 1.4,0.6 2.8,1.6 3.4,2.6 l 1.1,1.7 v 70.4 c 0,78 0.2,72.6 -3.2,74.7 -1.9,1.4 -5.2,1.4 -7.2,0.1 z" + id="path8" /><path + d="m 412.5,8929.8 c -3,-1 -7.1,-5 -8.5,-8.1 -1.1,-2.5 -1.2,-3.1 -1.2,-13.2 0,-12.4 0.3,-13.9 4.3,-18.1 4.3,-4.5 4.4,-4.6 27.4,-4.6 23,0 23.1,0 27.4,4.6 4,4.2 4.3,5.7 4.3,18.1 0,10.1 0,10.7 -1.2,13.2 -1.5,3.2 -5.6,7.1 -8.7,8.2 -3.3,1 -40.6,1 -43.8,-0.1 z m 39.5,-21.6 v -8.4 H 434.5 417 l -0.1,7.9 c 0,4.3 0,8.1 0.1,8.5 0.2,0.5 3.7,0.6 17.6,0.5 l 17.4,-0.1 z" + id="path10" /><path + d="m 318.8,8917.6 c -9.3,-1.5 -19.2,-5.4 -26.7,-10.4 -4.8,-3.2 -12.8,-11 -16.2,-15.8 -8.2,-11.4 -12.4,-24.3 -12.4,-38.3 0,-17 6.2,-32.4 17.8,-44.7 16.4,-17.2 40.3,-24.2 63.3,-18.4 25.8,6.5 44.8,28 48.6,54.9 0.7,5.1 0.3,16.2 -0.7,21.2 -2.9,13 -8.7,23.8 -18,33 -9.3,9.3 -19.3,14.8 -32.5,17.8 -5.7,1.2 -17.5,1.6 -23.2,0.7 z m 16.7,-13.8 c 6.7,-0.6 15.6,-4.1 22.5,-8.8 4.5,-3 10.1,-8.9 13.5,-14.1 10,-15.5 11,-34.7 2.5,-51.2 -6.7,-13 -18.1,-22.2 -32.9,-26.2 -3.2,-0.9 -5.2,-1.1 -12.4,-1.1 -10,0 -13.8,0.7 -21.5,4.3 -10.8,5.1 -18.7,12.7 -24,22.9 -4.3,8.3 -6.1,16.5 -5.6,26 0.4,7.1 1.7,12.7 4.5,18.6 3,6.2 5.2,9.5 9.9,14.3 8.3,8.7 19.6,14.2 31.7,15.4 3.7,0.5 5.6,0.5 11.8,-0.1 z" + id="path12" /><path + d="m 326,8893.5 c -0.8,-0.3 -2,-1.3 -2.7,-2 -1,-1.1 -1.2,-1.8 -1.2,-4.5 0,-3.1 0.1,-3.2 1.8,-4.8 1.3,-1.2 2.4,-1.7 4.2,-1.9 9.7,-1.1 13.8,-2.8 19,-7.6 4.8,-4.4 8.2,-11.6 8.3,-17 0,-4.7 2.1,-8.2 5.4,-9.1 3.7,-1 8,1.6 8.7,5.3 0.5,2.6 -0.5,10 -1.9,14.1 -2.3,6.8 -5.4,11.6 -10.5,16.5 -6.3,6.1 -13.1,9.6 -21.6,11 -5.4,0.8 -7.6,0.8 -9.5,0 z" + id="path14" /><path + d="m 752.2,8933.3 c -49.4,-10.4 -90.3,-19.3 -90.9,-19.7 -0.6,-0.4 -1.6,-1.3 -2,-2.1 -0.8,-1.3 -0.9,-6 -1.1,-81.5 l -0.2,-80.2 -3.3,2.7 c -4.3,3.4 -10.8,6.8 -16.3,8.5 -4.1,1.3 -5,1.4 -13,1.4 -7.9,0 -9,-0.1 -12.9,-1.3 -16.9,-5.2 -28.9,-17.6 -33.7,-35 -0.6,-2.4 -0.8,-5 -0.8,-11.4 0,-7.7 0.1,-8.8 1.4,-12.8 5.4,-17.7 19.6,-30.6 37.5,-33.7 4.6,-0.8 15.7,-0.4 19.9,0.7 17.2,4.7 29.5,17.1 34.6,35.1 l 1.1,3.8 0.1,65 0.1,65 81.2,17.7 c 44.7,9.7 81.4,17.5 81.6,17.3 0.2,-0.2 0.4,-21.2 0.5,-46.7 0.1,-45.5 0.1,-46.3 -0.8,-45.6 -0.5,0.4 -2.5,1.9 -4.3,3.2 -11,8.4 -26.3,11.5 -39.9,8 -4.5,-1.1 -12.1,-4.6 -15.7,-7.3 -13.4,-9.7 -20.8,-25.1 -19.8,-41.4 0.7,-12 5,-21.9 13.3,-30.5 9.3,-9.6 20.8,-14.5 34,-14.5 13,0 24.7,4.9 34,14.3 5.7,5.8 9.7,12.8 12.2,21.7 l 1.1,3.8 0.1,104.4 c 0.1,98.8 0,104.5 -0.7,106.1 -1.2,2.2 -3,3.5 -5.4,3.8 -1.5,0.1 -32.1,-6.2 -91.9,-18.8 z m 84.1,-21.2 v -24.4 l -1.1,-0.2 c -3,-0.7 -159.4,-34.7 -161,-35 l -1.8,-0.3 0.1,25 0.1,25 81,17.1 c 44.6,9.4 81.4,17.1 81.9,17.1 0.7,0.1 0.8,-1.4 0.8,-24.3 z m -27.8,-133.7 c 10,-1.8 19.4,-8.9 23.8,-17.9 2.6,-5.2 3.5,-9.4 3.6,-14.8 0,-5.9 -0.8,-9.4 -3.4,-15 -3.8,-8 -11.2,-14.4 -19.8,-17.2 -6.8,-2.3 -16.7,-1.7 -23.5,1.2 -9.2,4.1 -16.7,13 -19.2,22.8 -1.1,4.4 -0.7,13.9 0.7,18.3 1.6,4.8 4.4,9.2 8.5,13.3 7.7,7.8 18.7,11.3 29.3,9.3 z m -176.8,-30.7 c 9.8,-2.1 18.5,-9 23,-18.2 5.5,-11.5 4.2,-24.4 -3.7,-35.1 -5.7,-7.7 -16.2,-12.9 -26.1,-12.9 -10.2,0 -20.8,5.1 -26.7,12.9 -7.8,10.3 -9.2,23.6 -3.6,35.1 3.5,7.2 8.7,12.3 16.1,15.9 6.2,2.9 13.9,3.8 21,2.3 z" + id="path16" /><path + d="m 521.7,8874 v -6.9 h 7.9 7.9 v -11.6 -11.5 h -7.9 -7.9 v -7.1 -7.1 h 61.5 61.5 v 7.1 7.1 h -9.1 -9.1 v 11.6 11.6 h 9.1 9.1 v 6.9 6.9 h -61.5 -61.5 z m 53.2,-18.5 V 8844 h -11.6 -11.6 v 11.6 11.6 h 11.6 11.6 z m 37.4,0 V 8844 h -11.6 -11.6 v 11.6 11.6 h 11.6 11.6 z" + id="path18" /></g></svg> diff --git a/src/multimedia/doc/src/images/qS1FmgPVL.jpg b/src/multimedia/doc/src/images/qS1FmgPVL.jpg Binary files differnew file mode 100644 index 000000000..4dc2bb7c2 --- /dev/null +++ b/src/multimedia/doc/src/images/qS1FmgPVL.jpg diff --git a/src/multimedia/doc/src/images/sound-wave-small.jpg b/src/multimedia/doc/src/images/sound-wave-small.jpg Binary files differnew file mode 100644 index 000000000..1a873d94d --- /dev/null +++ b/src/multimedia/doc/src/images/sound-wave-small.jpg diff --git a/src/multimedia/doc/src/multimedia.qdoc b/src/multimedia/doc/src/multimedia-overview.qdoc index d5f0322c3..bb916ba57 100644 --- a/src/multimedia/doc/src/multimedia.qdoc +++ b/src/multimedia/doc/src/multimedia-overview.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the Qt for Multimedia module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,47 +14,59 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ + + /*! \page multimediaoverview.html -\title Multimedia +\title Multimedia Overview \brief A set of APIs for working with audio, video and camera devices. Multimedia support in Qt is provided by the \l{Qt Multimedia} module. The Qt Multimedia module provides a rich feature set that enables you to easily take -advantage of a platform's multimedia capabilities such as media playback and +advantage of a platform's multimedia capabilities, such as media playback and the use of camera devices. \section1 Features -Here are some examples of what can be done with Qt Multimedia APIs: +Here are some things you can do with the Qt Multimedia APIs: \list -\li Access raw audio devices for input and output -\li Play low latency sound effects -\li Play media files in playlists (such as compressed audio or video files) -\li Record audio and compress it +\li Access raw audio devices for input and output. +\li Play low latency sound effects. +\li Play media files in playlists (such as compressed audio or video files). +\li Record audio and compress it. \li Use a camera, including viewfinder, image capture, and movie recording -\li Play 3D positional audio with \l{Qt Audio Engine QML Types}{Qt Audio Engine} -\li Decode audio media files into memory for processing -\li Accessing video frames or audio buffers as they are played or recorded +\li Decode audio media files into memory for processing. \endlist \section1 Multimedia Components -Qt's multimedia APIs are categorized into four main components. More -information (including background information and class references) is -available here: +The Qt Multimedia APIs are categorized into three main components. More +information specific to each component is available in the overview pages. You +can also take a look at some \l{Multimedia Recipes}{recipes}. \list \li \l {Audio Overview} @@ -64,7 +76,7 @@ available here: \section1 Multimedia Recipes -For some quick recipes, look at the overviews above and consult this table: +For some quick recipes, see this table: \table 70% \header @@ -150,13 +162,14 @@ For some quick recipes, look at the overviews above and consult this table: \section1 Limitations The Qt Multimedia APIs build upon the multimedia framework of the underlying -platform. This can mean that support for various codecs or containers can vary -between machines, depending on what the end user has installed. +platform. This can mean that support for various codecs, or containers will vary +between machines. This support depends on what the end user has installed. \section1 Changes from Previous Versions -If you previously used Qt Multimedia in Qt 5, please see \l {Changes in Qt Multimedia} -for more information on what changed, and what you might need to change when porting code. +If you previously used Qt Multimedia in Qt 5, see +\l{Changes in Qt Multimedia} for more information on what has changed, and what +you might need to change when porting code to Qt 6. \section1 Reference Documentation diff --git a/src/multimedia/doc/src/platform-notes-apple.qdoc b/src/multimedia/doc/src/platform-notes-apple.qdoc index ac0655c5b..bd8636ee4 100644 --- a/src/multimedia/doc/src/platform-notes-apple.qdoc +++ b/src/multimedia/doc/src/platform-notes-apple.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the FOO module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,30 +14,42 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page qtmultimedia-apple.html -\title Qt Multimedia on iOS +\title Qt Multimedia on macOS and iOS \brief Platform notes for iOS This page covers the availability of Qt Multimedia features on iOS and macOS. \section1 Limitations -Since Qt Multimedia for iOS uses the camera and microphone, the \c Info.plist assigned to -QMAKE_INFO_PLIST in the project file must contain the key -\c NSCameraUsageDescription and NSMicrophoneUsageDescription. Otherwise the application will -abort on startup. See Info.plist documentation from Apple for more information -regarding this key. +Since Qt Multimedia for iOS uses the camera and microphone, the \c Info.plist +assigned to QMAKE_INFO_PLIST in the project file must contain the keys +\c NSCameraUsageDescription and \c NSMicrophoneUsageDescription. Otherwise, the +application will abort on startup. See \l{Info.plist} documentation from Apple +for more information regarding this key. */ diff --git a/src/multimedia/doc/src/plugins/qml-multimedia.qdoc b/src/multimedia/doc/src/plugins/qml-multimedia.qdoc index b6df70973..f4a57b2a3 100644 --- a/src/multimedia/doc/src/plugins/qml-multimedia.qdoc +++ b/src/multimedia/doc/src/plugins/qml-multimedia.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the FOO module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,13 +14,25 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ @@ -35,14 +47,17 @@ \section1 Overview - The Qt Multimedia module gives developers a simplified way to use audio and video playback, and access camera functionality. The Multimedia QML API provides a QML friendly interface to these features. + The Qt Multimedia module gives developers a simplified way to use audio and + video playback, and access camera functionality. The Multimedia QML API + provides a QML friendly interface to these features. \section1 Types \section2 Audio \l Audio is an easy way to add audio playback to a Qt Quick - scene. Qt Multimedia provides properties for control, methods (functions) and signals. + scene. Qt Multimedia provides properties for control, methods (functions), + and signals. The code extract below shows the creation and use of an Audio instance. @@ -66,9 +81,14 @@ \endqml - The snippet above shows how the inclusion of \e playMusic enables audio features on the type that contains it. So that when the parent's MouseArea is clicked the \l {Audio::play()}{play()} method of Audio is run. Other typical audio control methods are available such as \l {Audio::pause}{pause()} and \l {Audio::stop()}{stop()}. + The snippet above shows how the inclusion of \e playMusic enables audio + features on the type that contains it. So that when the parent's MouseArea + is clicked the \l {Audio::play()}{play()} method of Audio is run. Other + typical audio control methods are available such as \l {Audio::pause}{pause()} + and \l {Audio::stop()}{stop()}. - Much of the getting / setting of \l Audio parameters is done through properties. These include + Much of the getting and setting of \l Audio parameters is done through + properties. These include: \table 70% \header \li Property @@ -117,7 +137,8 @@ \li A description of the current error condition. \endtable - The set of signals available allow the developer to create custom behavior when the following events occur, + The set of signals available allow the developer to create custom behavior + when the following events occur: \table 70% \header @@ -147,7 +168,10 @@ \section2 Video - Adding video playback, with sound, to a Qt Quick scene is also easy. The process is very similar to that of Audio above, in fact \l {Video} shares many of the property names, methods and signals. Here is the equivalent sample code to implement video playback in a scene + Adding video playback, with sound, to a Qt Quick scene is also easy. The + process is very similar to that of Audio above, in fact \l {Video} shares + many of the property names, methods and signals. Here is the equivalent + sample code to implement video playback in a scene. \qml @@ -175,13 +199,28 @@ There are similar features like \l {Video::play()}{play()} with new features specific to video. - In the above sample when the parent of MouseArea is clicked, an area of 800x600 pixels with an id of 'video', the source "video.avi" will play in that area. Notice also that signals for the \l Keys have been defined so that a spacebar will toggle the pause button; the left arrow will move the current position in the video to 5 seconds previously; and the right arrow will advance the current position in the video by 5 seconds. + The behavior and properties of the video object are defined in the + above snippet. The source file (video.avi) plays when you click the parent + of MouseArea. The video plays in an area of 800 by 600 pixels, and its \b id + property has the value \b{video}. + + Notice that because signals for the \l Keys have been defined pressing the: + \list + \li \b Spacebar toggles the pause button. + \li \b{Left Arrow} moves the current position in the video to 5 seconds + previously. + \li {Right Arrow} advances the current position in the video by 5 seconds. + \endlist - Most of the differences will obviously be about video control and information. There are many properties associated with \l {Video}, most of them deal with meta-data, control of the video media and aspects of presentation. + Most of the differences will obviously be about video control and + information. + There are many properties associated with \l {Video}, most of them deal with + meta-data, control of the video media and aspects of presentation. \section2 SoundEffect - \l SoundEffect provides a way to play short sound effects, like in video games. Multiple sound effect instances can be played simultaneously. + \l SoundEffect provides a way to play short sound effects, as used in video + games. Multiple sound effect instances can be played simultaneously. You should use \l Audio for music playback. \qml diff --git a/src/multimedia/doc/src/qm-external-pages.qdoc b/src/multimedia/doc/src/qm-external-pages.qdoc new file mode 100644 index 000000000..ce1066941 --- /dev/null +++ b/src/multimedia/doc/src/qm-external-pages.qdoc @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the FOO module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \externalpage https://gstreamer.freedesktop.org + \title gstreamer +*/ +/*! + \externalpage https://en.wikipedia.org/wiki/Pixel_Format + \title pixel format +*/ + +/*! + \externalpage https://developer.apple.com/documentation/bundleresources/information_property_list + \title Info.plist +*/ + +/*! + \externalpage https://www.wix.com/blog/photography/2018/10/04/photography-terms/ + \title photo glossary +*/ + +/*! + \externalpage https://doc.qt.io/qt-6/qtqml-syntax-imports.html + \title qtqml import syntax +*/ diff --git a/src/multimedia/doc/src/qtmultimedia-index.qdoc b/src/multimedia/doc/src/qtmultimedia-index.qdoc index 598a67456..6cd6c46b2 100644 --- a/src/multimedia/doc/src/qtmultimedia-index.qdoc +++ b/src/multimedia/doc/src/qtmultimedia-index.qdoc @@ -1,11 +1,11 @@ /**************************************************************************** ** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** -** This file is part of the documentation of the Qt Toolkit. +** This file is part of the Qt for Multimedia module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:FDL$ +** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the @@ -14,13 +14,25 @@ ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** ** $QT_END_LICENSE$ ** ****************************************************************************/ @@ -28,14 +40,13 @@ /*! \page qtmultimedia-index.html \title Qt Multimedia + \image noun_Media_166644.svg "image of multimedia icons, courtesy of misirlou from the Noun Project" \brief The Qt Multimedia module provides APIs for audio, video and - camera-related functionality. + camera-related functionality - Qt Multimedia is an essential module that provides a rich set of QML types + Qt Multimedia is an add-on module that provides a rich set of QML types and C++ classes to handle multimedia content. It also provides necessary - APIs to access the camera functionality. The included - \l{Qt Audio Engine QML Types}{Qt Audio Engine} provides types for - 3D positional audio playback and content management. + APIs to access the camera functionality. The functionality of this module is divided into the following submodules: @@ -50,14 +61,14 @@ \section1 Getting Started - The QML types can be imported into your applciation using the following - import statement in your \c {.qml} file. + The QML types can be \l{qtqml import syntax}{imported} into an + application using the following statement in your \c {.qml} file. - \qml \QtMinorVersion - import QtMultimedia 5.\1 + \qml + import QtMultimedia \endqml - If you intend to use the C++ classes in your application, include the C++ + If you want to use the C++ classes in your application, include the C++ definitions using the following directive: \code @@ -95,8 +106,8 @@ \li Access camera viewfinder frames \row \li MediaPlayer - \li Add media playback functionality to a scene. It is same as Audio type, - but can be used for video playback with the VideoOutput type. + \li Add media playback functionality to a scene. It is same as the Audio + type, but can be used for video playback with the VideoOutput type. \row \li \l {QtMultimedia::Video}{Video} \li Add Video playback functionality to a scene. It uses MediaPlayer and @@ -111,31 +122,32 @@ \li QAudioSink \li Sends audio data to an audio output device \row - \li QAudioRecorder + \li \l QAudioRecorder \li Record media content from an audio source. \row - \li QCamera + \li \l QCamera \li Access camera viewfinder. \row \li QImageCapture \li Capture still images with a camera. \row - \li QMediaRecorder + \li \l QMediaRecorder \li Record media content from a camera source. \row - \li QMediaPlayer + \li \l QMediaPlayer \li Playback media from a source. \row - \li QMediaPlaylist + \li \l QMediaPlaylist \li List of media to be played. \row - \li QVideoSink + \li \l QVideoSink \li Class for video presentation. \endtable \section1 Licenses and Attributions - The Qt Quick Multimedia module is available under commercial licenses from \l{The Qt Company}. + The Qt Quick Multimedia module is available under commercial licenses from + \l{The Qt Company}. In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are \l{GNU Lesser General Public License, version 3}, or @@ -146,7 +158,7 @@ \section2 Guides \list - \li \l Multimedia - overview of multimedia support in Qt + \li \l{Multimedia Overview} \li \l{Audio Overview} \li \l{Video Overview} \li \l{Camera Overview} @@ -154,9 +166,10 @@ \section2 Platform Notes - The \l{Qt Multimedia Backends} wiki provides a summary of features - supported by each platform plugin made available by this module. The - following topics provide more platform-specific information. + For most features, Qt Multimedia builds upon the multimedia framework of the + underlying operating system. Therefore there are several multimedia back ends + based on different technologies and APIs. For further details, see the + \l{Qt Multimedia Backends}{Qt Multimedia back ends wiki}. \list \li \l{Qt Multimedia on macOS and iOS}{iOS} diff --git a/src/multimedia/doc/src/qtmultimedia5.qdoc b/src/multimedia/doc/src/qtmultimedia-qml-types.qdoc index 16e0e581b..16e0e581b 100644 --- a/src/multimedia/doc/src/qtmultimedia5.qdoc +++ b/src/multimedia/doc/src/qtmultimedia-qml-types.qdoc diff --git a/src/multimediaquick/camerafocus.qdoc b/src/multimediaquick/camerafocus.qdoc index 00177ec61..916210fd6 100644 --- a/src/multimediaquick/camerafocus.qdoc +++ b/src/multimediaquick/camerafocus.qdoc @@ -40,16 +40,16 @@ QT_BEGIN_NAMESPACE /*! - \qmltype CameraFocus + \qmltype Camera \instantiates QDeclarativeCameraFocus \inqmlmodule QtMultimedia - \brief An interface for focus related camera settings. + \brief An interface for focus and zoom related camera settings. \ingroup multimedia_qml \ingroup camera_qml This type allows control over manual and automatic focus settings, including information about any parts of the - camera frame that are selected for autofocusing. + camera frame that are selected for auto focusing. It should not be constructed separately, instead the \c focus property of a \l Camera should be used. |
