diff options
| author | Topi Reinio <topi.reinio@qt.io> | 2021-07-09 12:53:42 +0200 |
|---|---|---|
| committer | Nicholas Bennett <nicholas.bennett@qt.io> | 2021-07-09 18:28:57 +0000 |
| commit | 1ca3ebd738c56d06729233e417088364ff7ab233 (patch) | |
| tree | 3b074e7a85ba40d314dd2b70d97f5a0f29566334 /src/multimedia | |
| parent | a7310e006498155efed33256eabc34e548499e38 (diff) | |
Doc: Part 1 Fix Qt Multimedia documentation issues
TODO:
* src/multimedia/audio/qaudiobuffer.cpp:333: (qdoc) warning: Cannot find 'QAudioBuffer::StereoFrame'
* multimediaquick/camerafocus.qdoc content refers to now-removed classes
* multimediawidgets module doc needs CMake build instructions/snippet
* Lots of undocumented parameters, enum values, other minor things
Pick-to: 6.2
Change-Id: I4861aa0edf2904e5e43783f5167c5d2ba575b91b
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Diffstat (limited to 'src/multimedia')
23 files changed, 171 insertions, 500 deletions
diff --git a/src/multimedia/audio/qaudiodecoder.cpp b/src/multimedia/audio/qaudiodecoder.cpp index 8b8db59ba..610c6b332 100644 --- a/src/multimedia/audio/qaudiodecoder.cpp +++ b/src/multimedia/audio/qaudiodecoder.cpp @@ -95,7 +95,8 @@ bool QAudioDecoder::isSupported() const } /*! - Returns true if the decoder is currently running and decoding audio data. + \property QAudioDecoder::isDecoding + \brief \c true if the decoder is currently running and decoding audio data. */ bool QAudioDecoder::isDecoding() const { @@ -103,7 +104,8 @@ bool QAudioDecoder::isDecoding() const } /*! - Returns the current error state. + \property QAudioDecoder::error + \brief The current error state. */ QAudioDecoder::Error QAudioDecoder::error() const { @@ -113,8 +115,8 @@ QAudioDecoder::Error QAudioDecoder::error() const } /*! - Returns a human readable description of the current error. - Returns an empty string is there is no error. + Returns a human readable description of the current error, or + an empty string is there is no error. */ QString QAudioDecoder::errorString() const { @@ -270,16 +272,6 @@ QAudioBuffer QAudioDecoder::read() const // Enums /*! - \enum QAudioDecoder::State - - Defines the current state of a media player. - - \value StoppedState The decoder is not decoding. Decoding will - start at the start of the media. - \value DecodingState The audio player is currently decoding media. -*/ - -/*! \enum QAudioDecoder::Error Defines a media player error condition. @@ -301,12 +293,6 @@ QAudioBuffer QAudioDecoder::read() const */ /*! - \fn void QAudioDecoder::stateChanged(State state) - - Signal the \a state of the decoder object has changed. -*/ - -/*! \fn void QAudioDecoder::sourceChanged() Signals that the current source of the decoder has changed. @@ -315,14 +301,6 @@ QAudioBuffer QAudioDecoder::read() const */ /*! - \fn void QAudioDecoder::formatChanged(const QAudioFormat &format) - - Signals that the current audio format of the decoder has changed to \a format. - - \sa audioFormat(), setAudioFormat() -*/ - -/*! \fn void QAudioDecoder::bufferReady() Signals that a new decoded audio buffer is available to be read. @@ -368,22 +346,6 @@ QAudioBuffer QAudioDecoder::read() const // Properties /*! - \property QAudioDecoder::state - \brief the audio decoder's playback state. - - By default this property is QAudioDecoder::Stopped - - \sa start(), stop() -*/ - -/*! - \property QAudioDecoder::error - \brief a string describing the last error condition. - - \sa error() -*/ - -/*! \property QAudioDecoder::source \brief the active filename being decoded by the decoder object. */ diff --git a/src/multimedia/audio/qaudioformat.cpp b/src/multimedia/audio/qaudioformat.cpp index c9217372b..bdbac13f3 100644 --- a/src/multimedia/audio/qaudioformat.cpp +++ b/src/multimedia/audio/qaudioformat.cpp @@ -142,28 +142,44 @@ QT_BEGIN_NAMESPACE */ /*! - \enum AudioChannel + \enum QAudioFormat::AudioChannelPosition - The audio channels follow the standard definition used in + Describes the possible audio channel positions. These follow the standard + definition used in the 22.2 surround sound configuration. - \value Mono - \value Left - \value Right - \value Center + \value UnknownPosition Unknown position + \value FrontLeft + \value FrontRight + \value FrontCenter \value LFE Low Frequence Effect channel (Subwoofer) - \value RearLeft - \value RearRight, - \value SideLeft, + \value BackLeft + \value BackRight + \value FrontLeftOfCenter + \value FrontRightOfCenter + \value BackCenter + \value LFE2 + \value SideLeft \value SideRight - \value RearCenter + \value TopFrontLeft + \value TopFrontRight + \value TopFrontCenter + \value TopCenter + \value TopBackLeft + \value TopBackRight + \value TopSideLeft + \value TopSideRight + \value TopBackCenter + \value BottomFrontCenter + \value BottomFrontLeft + \value BottomFrontRight */ /*! - \enum ChannelConfig + \enum QAudioFormat::ChannelConfig This enum describes a standardized audio channel layout. The most common configurations are Mono, Stereo, 2.1 - (stereo plus low frequency) , 5.1 surround and 7.1 surround configurations. + (stereo plus low frequency), 5.1 surround, and 7.1 surround configurations. \value ChannelConfigUnknown The channel configuration is not known. \value ChannelConfigMono The audio has one Center channel diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp index 95cdc02e7..ba07022ab 100644 --- a/src/multimedia/audio/qaudiooutput.cpp +++ b/src/multimedia/audio/qaudiooutput.cpp @@ -87,16 +87,6 @@ This property can be used to select any other output device listed by QMediaDevices::audioOutputs(). */ -/*! - \property QAudioOutput::audioRole - \brief the role of the audio played by this output. - - It can be set to specify the type of audio being played, allowing the system to make - appropriate decisions when it comes to volume, routing or post-processing. - - \sa supportedAudioRoles() -*/ - QAudioOutput::QAudioOutput(QObject *parent) : QAudioOutput(QMediaDevices::defaultAudioOutput(), parent) {} diff --git a/src/multimedia/audio/qaudiosystem.cpp b/src/multimedia/audio/qaudiosystem.cpp index 5c43b68f6..f1fd5bb30 100644 --- a/src/multimedia/audio/qaudiosystem.cpp +++ b/src/multimedia/audio/qaudiosystem.cpp @@ -59,85 +59,85 @@ QT_BEGIN_NAMESPACE */ /*! - \fn virtual void QPlatformAudioSink::start(QIODevice* device) + \fn void QPlatformAudioSink::start(QIODevice* device) Uses the \a device as the QIODevice to transfer data. */ /*! - \fn virtual QIODevice* QPlatformAudioSink::start() + \fn QIODevice* QPlatformAudioSink::start() Returns a pointer to the QIODevice being used to handle the data transfer. This QIODevice can be used to write() audio data directly. */ /*! - \fn virtual void QPlatformAudioSink::stop() + \fn void QPlatformAudioSink::stop() Stops the audio output. */ /*! - \fn virtual void QPlatformAudioSink::reset() + \fn void QPlatformAudioSink::reset() Drops all audio data in the buffers, resets buffers to zero. */ /*! - \fn virtual void QPlatformAudioSink::suspend() + \fn void QPlatformAudioSink::suspend() Stops processing audio data, preserving buffered audio data. */ /*! - \fn virtual void QPlatformAudioSink::resume() + \fn void QPlatformAudioSink::resume() Resumes processing audio data after a suspend() */ /*! - \fn virtual qsizetype QPlatformAudioSink::bytesFree() const + \fn qsizetype QPlatformAudioSink::bytesFree() const Returns the free space available in bytes in the audio buffer. */ /*! - \fn virtual void QPlatformAudioSink::setBufferSize(qsizetype value) + \fn void QPlatformAudioSink::setBufferSize(qsizetype value) Sets the audio buffer size to \a value in bytes. */ /*! - \fn virtual qsizetype QPlatformAudioSink::bufferSize() const + \fn qsizetype QPlatformAudioSink::bufferSize() const Returns the audio buffer size in bytes. */ /*! - \fn virtual qint64 QPlatformAudioSink::processedUSecs() const + \fn qint64 QPlatformAudioSink::processedUSecs() const Returns the amount of audio data processed since start() was called in milliseconds. */ /*! - \fn virtual QAudio::Error QPlatformAudioSink::error() const + \fn QAudio::Error QPlatformAudioSink::error() const Returns the error state. */ /*! - \fn virtual QAudio::State QPlatformAudioSink::state() const + \fn QAudio::State QPlatformAudioSink::state() const Returns the state of audio processing. */ /*! - \fn virtual void QPlatformAudioSink::setFormat(const QAudioFormat& fmt) + \fn void QPlatformAudioSink::setFormat(const QAudioFormat& fmt) Set the QAudioFormat to use to \a fmt. Setting the format is only allowable while in QAudio::StoppedState. */ /*! - \fn virtual QAudioFormat QPlatformAudioSink::format() const + \fn QAudioFormat QPlatformAudioSink::format() const Returns the QAudioFormat being used. */ /*! - \fn virtual void QPlatformAudioSink::setVolume(qreal volume) + \fn void QPlatformAudioSink::setVolume(qreal volume) Sets the volume. Where \a volume is between 0.0 and 1.0. */ /*! - \fn virtual qreal QPlatformAudioSink::volume() const + \fn qreal QPlatformAudioSink::volume() const Returns the volume in the range 0.0 and 1.0. */ @@ -169,74 +169,74 @@ QT_BEGIN_NAMESPACE */ /*! - \fn virtual void QPlatformAudioSource::start(QIODevice* device) + \fn void QPlatformAudioSource::start(QIODevice* device) Uses the \a device as the QIODevice to transfer data. */ /*! - \fn virtual QIODevice* QPlatformAudioSource::start() + \fn QIODevice* QPlatformAudioSource::start() Returns a pointer to the QIODevice being used to handle the data transfer. This QIODevice can be used to read() audio data directly. */ /*! - \fn virtual void QPlatformAudioSource::stop() + \fn void QPlatformAudioSource::stop() Stops the audio input. */ /*! - \fn virtual void QPlatformAudioSource::reset() + \fn void QPlatformAudioSource::reset() Drops all audio data in the buffers, resets buffers to zero. */ /*! - \fn virtual void QPlatformAudioSource::suspend() + \fn void QPlatformAudioSource::suspend() Stops processing audio data, preserving buffered audio data. */ /*! - \fn virtual void QPlatformAudioSource::resume() + \fn void QPlatformAudioSource::resume() Resumes processing audio data after a suspend(). */ /*! - \fn virtual qsizetype QPlatformAudioSource::bytesReady() const + \fn qsizetype QPlatformAudioSource::bytesReady() const Returns the amount of audio data available to read in bytes. */ /*! - \fn virtual void QPlatformAudioSource::setBufferSize(qsizetype value) + \fn void QPlatformAudioSource::setBufferSize(qsizetype value) Sets the audio buffer size to \a value in milliseconds. */ /*! - \fn virtual qsizetype QPlatformAudioSource::bufferSize() const + \fn qsizetype QPlatformAudioSource::bufferSize() const Returns the audio buffer size in milliseconds. */ /*! - \fn virtual qint64 QPlatformAudioSource::processedUSecs() const + \fn qint64 QPlatformAudioSource::processedUSecs() const Returns the amount of audio data processed since start() was called in milliseconds. */ /*! - \fn virtual QAudio::Error QPlatformAudioSource::error() const + \fn QAudio::Error QPlatformAudioSource::error() const Returns the error state. */ /*! - \fn virtual QAudio::State QPlatformAudioSource::state() const + \fn QAudio::State QPlatformAudioSource::state() const Returns the state of audio processing. */ /*! - \fn virtual void QPlatformAudioSource::setFormat(const QAudioFormat& fmt) + \fn void QPlatformAudioSource::setFormat(const QAudioFormat& fmt) Set the QAudioFormat to use to \a fmt. Setting the format is only allowable while in QAudio::StoppedState. */ /*! - \fn virtual QAudioFormat QPlatformAudioSource::format() const + \fn QAudioFormat QPlatformAudioSource::format() const Returns the QAudioFormat being used */ diff --git a/src/multimedia/audio/qsoundeffect.cpp b/src/multimedia/audio/qsoundeffect.cpp index 80fcef9c6..523f993a5 100644 --- a/src/multimedia/audio/qsoundeffect.cpp +++ b/src/multimedia/audio/qsoundeffect.cpp @@ -713,31 +713,6 @@ QSoundEffect::Status QSoundEffect::status() const } /*! - \qmlproperty string QtMultimedia::SoundEffect::category - - This property contains the \e category of this sound effect. - - Some platforms can perform different audio routing - for different categories, or may allow the user to - set different volume levels for different categories. - - This setting will be ignored on platforms that do not - support audio categories. -*/ -/*! - \property QSoundEffect::category - - This property contains the \e category of this sound effect. - - Some platforms can perform different audio routing - for different categories, or may allow the user to - set different volume levels for different categories. - - This setting will be ignored on platforms that do not - support audio categories. -*/ - -/*! \qmlmethod QtMultimedia::SoundEffect::stop() Stop current playback. @@ -770,8 +745,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::sourceChanged() The \c sourceChanged signal is emitted when the source has been changed. - - The corresponding handler is \c onSourceChanged. */ /*! \fn void QSoundEffect::loadedChanged() @@ -782,8 +755,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::loadedChanged() The \c loadedChanged signal is emitted when the loading state has changed. - - The corresponding handler is \c onLoadedChanged. */ /*! @@ -795,8 +766,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::loopCountChanged() The \c loopCountChanged signal is emitted when the initial number of loops has changed. - - The corresponding handler is \c onLoopCountChanged. */ /*! @@ -808,8 +777,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::loopsRemainingChanged() The \c loopsRemainingChanged signal is emitted when the remaining number of loops has changed. - - The corresponding handler is \c onLoopsRemainingChanged. */ /*! @@ -821,8 +788,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::volumeChanged() The \c volumeChanged signal is emitted when the volume has changed. - - The corresponding handler is \c onVolumeChanged. */ /*! @@ -834,8 +799,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::mutedChanged() The \c mutedChanged signal is emitted when the mute state has changed. - - The corresponding handler is \c onMutedChanged. */ /*! @@ -847,8 +810,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::playingChanged() The \c playingChanged signal is emitted when the playing property has changed. - - The corresponding handler is \c onPlayingChanged. */ /*! @@ -860,21 +821,6 @@ void QSoundEffect::stop() \qmlsignal QtMultimedia::SoundEffect::statusChanged() The \c statusChanged signal is emitted when the status property has changed. - - The corresponding handler is \c onStatusChanged. -*/ - -/*! - \fn void QSoundEffect::categoryChanged() - - The \c categoryChanged signal is emitted when the category property has changed. -*/ -/*! - \qmlsignal QtMultimedia::SoundEffect::categoryChanged() - - The \c categoryChanged signal is emitted when the category property has changed. - - The corresponding handler is \c onCategoryChanged. */ QT_END_NAMESPACE diff --git a/src/multimedia/camera/qcamera.cpp b/src/multimedia/camera/qcamera.cpp index 5fca81320..16f9840ed 100644 --- a/src/multimedia/camera/qcamera.cpp +++ b/src/multimedia/camera/qcamera.cpp @@ -256,17 +256,13 @@ QCamera::Features QCamera::supportedFeatures() const Same as setActive(true). If the camera can't be started for some reason, the errorOccurred() signal is emitted. - - While the camera state is changed to QCamera::ActiveState, - starting the camera service can be asynchronous with the actual - status reported with QCamera::status property. */ /*! \fn void QCamera::stop() Stops the camera. - \sa unload(), QCamera::InactiveStatus + \sa unload() */ /*! @@ -354,36 +350,6 @@ void QCamera::setCameraFormat(const QCameraFormat &format) } /*! - \enum QCamera::Status - - This enum holds the current status of the camera. - - \value ActiveStatus - The camera has been started and can produce data. - The viewfinder displays video frames in active state. - Depending on backend, changing some camera settings like - capture mode, codecs or resolution in ActiveState may lead - to changing the camera status to LoadedStatus and StartingStatus while - the settings are applied and back to ActiveStatus when the camera is ready. - \value StartingStatus - The camera is starting in result of state transition to QCamera::ActiveState. - The camera service is not ready to capture yet. - \value StoppingStatus - The camera is stopping in result of state transition from QCamera::ActiveState - to QCamera::LoadedState or QCamera::UnloadedState. - \value InactiveStatus - The camera is not currently active. - \value UnavailableStatus - The camera or camera backend is not available. -*/ - - -/*! - \property QCamera::status - \brief The current status of the camera object. -*/ - -/*! \enum QCamera::Error This enum holds the last error code. @@ -393,17 +359,10 @@ void QCamera::setCameraFormat(const QCameraFormat &format) */ /*! - \fn void QCamera::error(QCamera::Error value) - \obsolete - - Use errorOccurred() instead. -*/ - -/*! - \fn void QCamera::errorOccurred(QCamera::Error value) - \since 5.15 + \fn void QCamera::errorOccurred(QCamera::Error error, const QString &errorString) - Signal emitted when error state changes to \a value. + This signal is emitted when error state changes to \a error. A description + of the error is provided as \a errorString. */ /*! @@ -426,24 +385,6 @@ void QCamera::setCameraFormat(const QCameraFormat &format) */ /*! - \fn QCamera::stateChanged(QCamera::State state) - - Signals the camera \a state has changed. - - Usually the state changes is caused by calling - load(), unload(), start() and stop(), - but the state can also be changed change as a result of camera error. -*/ - -/*! - \fn QCamera::statusChanged(QCamera::Status status) - - Signals the camera \a status has changed. - -*/ - - -/*! \property QCamera::focusMode \brief the current camera focus mode. @@ -606,33 +547,6 @@ void QCamera::zoomTo(float factor, float rate) */ /*! - \fn void QCamera::opticalZoomChanged(qreal value) - - Signal emitted when optical zoom value changes to new \a value. -*/ - -/*! - \fn void QCamera::digitalZoomChanged(qreal value) - - Signal emitted when digital zoom value changes to new \a value. -*/ - -/*! - \fn void QCamera::maximumOpticalZoomChanged(qreal zoom) - - Signal emitted when the maximum supported optical \a zoom value changed. -*/ - -/*! - \fn void QCamera::maximumDigitalZoomChanged(qreal zoom) - - Signal emitted when the maximum supported digital \a zoom value changed. - - The maximum supported zoom value can depend on other camera settings, - like capture mode or resolution. -*/ - -/*! \property QCamera::flashMode \brief The flash mode being used. @@ -937,13 +851,6 @@ void QCamera::setAutoExposureTime() */ /*! - \fn void QCamera::exposureTimeRangeChanged() - - Signal emitted when the exposure time range has changed. -*/ - - -/*! \fn void QCamera::isoSensitivityChanged(int value) Signal emitted when sensitivity changes to \a value. diff --git a/src/multimedia/camera/qimagecapture.cpp b/src/multimedia/camera/qimagecapture.cpp index 9dc2b3725..1d1584fa5 100644 --- a/src/multimedia/camera/qimagecapture.cpp +++ b/src/multimedia/camera/qimagecapture.cpp @@ -204,8 +204,11 @@ QString QImageCapture::errorString() const } /*! - Returns the meta data that will get embedded into the image. A couple of additional fields - such as a time stamp or location might get added by the camera backend. + \property QImageCapture::metaData + \brief The meta data that will get embedded into the image. + + \note Additional fields such as a time stamp or location may get added by + the camera backend. */ QMediaMetaData QImageCapture::metaData() const { @@ -343,19 +346,13 @@ int QImageCapture::capture() */ /*! - \fn QImageCapture::error(int id, QImageCapture::Error error, const QString &errorString) + \fn QImageCapture::errorOccurred(int id, QImageCapture::Error error, const QString &errorString); Signals that the capture request \a id has failed with an \a error and \a errorString description. */ /*! - \fn QImageCapture::bufferFormatChanged(QVideoFrameFormat::PixelFormat format) - - Signal emitted when the buffer \a format for the buffer image capture has changed. -*/ - -/*! \fn QImageCapture::imageExposed(int id) Signal emitted when the frame with request \a id was exposed. @@ -369,15 +366,6 @@ int QImageCapture::capture() */ /*! - \fn QImageCapture::imageMetadataAvailable(int id, const QString &key, const QVariant &value) - - Signals that a metadata for an image with request \a id is available. Also - includes the \a key and \a value of the metadata. - - This signal is emitted between imageExposed and imageSaved signals. -*/ - -/*! \fn QImageCapture::imageAvailable(int id, const QVideoFrame &frame) Signal emitted when QImageCapture::CaptureToBuffer is set and @@ -392,7 +380,8 @@ int QImageCapture::capture() */ /*! - Returns the image format. + \property QImageCapture::fileFormat + \brief The image format. */ QImageCapture::FileFormat QImageCapture::fileFormat() const @@ -512,7 +501,7 @@ void QImageCapture::setResolution(int width, int height) } /*! - \enum QImageCapture::EncodingQuality + \enum QImageCapture::Quality Enumerates quality encoding levels. @@ -524,7 +513,8 @@ void QImageCapture::setResolution(int width, int height) */ /*! - Returns the image encoding quality. + \property QImageCapture::quality + \brief The image encoding quality. */ QImageCapture::Quality QImageCapture::quality() const { diff --git a/src/multimedia/doc/QtMultimediaDoc b/src/multimedia/doc/QtMultimediaDoc index e57c3595b..262d39738 100644 --- a/src/multimedia/doc/QtMultimediaDoc +++ b/src/multimedia/doc/QtMultimediaDoc @@ -1,2 +1,9 @@ #include <QtMultimedia/QtMultimedia> #include <QtMultimediaWidgets/QtMultimediaWidgets> + +#include "../audio/qaudiosystem_p.h" +#include "../platform/qplatformaudiodecoder_p.h" +#include "../platform/qplatformcamera_p.h" +#include "../platform/qplatformmediaencoder_p.h" +#include "../platform/qplatformimagecapture_p.h" +#include "../platform/qplatformvideosink_p.h" diff --git a/src/multimedia/doc/qtmultimedia.qdocconf b/src/multimedia/doc/qtmultimedia.qdocconf index 260e62b89..7e9a97b54 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 = . +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/snippets/CMakeLists.txt b/src/multimedia/doc/snippets/CMakeLists.txt new file mode 100644 index 000000000..4df8fd9b1 --- /dev/null +++ b/src/multimedia/doc/snippets/CMakeLists.txt @@ -0,0 +1,12 @@ +cmake_minimum_required(VERSION 3.1.0) + +project(multimedia_cppsnippets) + +add_executable(mytarget + multimedia-snippets/media.cpp +) + +# ![0] +find_package(Qt6 COMPONENTS Multimedia REQUIRED) +target_link_libraries(mytarget PRIVATE Qt6::Multimedia) +# ![0] diff --git a/src/multimedia/doc/src/audiooverview.qdoc b/src/multimedia/doc/src/audiooverview.qdoc index bfff29689..d4c3116ba 100644 --- a/src/multimedia/doc/src/audiooverview.qdoc +++ b/src/multimedia/doc/src/audiooverview.qdoc @@ -65,14 +65,11 @@ Here is how you play a local file using C++: \snippet multimedia-snippets/media.cpp Local playback -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 QMediaRecorder class allows you to compress audio data from an input device and record it. - \snippet multimedia-snippets/media.cpp Audio recorder + \snippet multimedia-snippets/media.cpp Media recorder QMediaCaptureSession provides support for more complex use cases involving the capturing and recording of audio. diff --git a/src/multimedia/doc/src/qtmultimedia-cpp.qdoc b/src/multimedia/doc/src/qtmultimedia-cpp.qdoc index f75ecbfe2..01d5579af 100644 --- a/src/multimedia/doc/src/qtmultimedia-cpp.qdoc +++ b/src/multimedia/doc/src/qtmultimedia-cpp.qdoc @@ -30,19 +30,18 @@ \title Qt Multimedia Module C++ Classes \ingroup modules \qtvariable multimedia + \qtcmakepackage Multimedia \brief The \l {Qt Multimedia} module provides audio, video and camera functionality. - To enable Qt Multimedia in a project, add this directive into the + To enable Qt Multimedia in a project, add this directive into your C++ files: \snippet doc_src_qtmultimedia.cpp 0 - To link against the C++ libraries, add the following to your \c qmake project - file: - - \snippet doc_src_qtmultimedia.pro 0 + \include module-use.qdocinc using qt module + \snippet ../src/multimedia/doc/snippets/CMakeLists.txt 0 */ /*! @@ -54,7 +53,7 @@ QML alternatives. If your application is serving complex use cases such as decoding media files, accessing video or audio buffers, use the C++ alternative. For more details about the complex audio, video, and camera use - cases supported by the C++ classes, refer to \l {Multimedia}{Multimedia Overview}. + cases supported by the C++ classes, refer to \l {Qt Multimedia}{Multimedia Overview}. \section1 Namespaces \annotatedlist multimedia-namespaces diff --git a/src/multimedia/platform/gstreamer/common/qgstutils.cpp b/src/multimedia/platform/gstreamer/common/qgstutils.cpp index 5d88f7e13..de5b05cd2 100644 --- a/src/multimedia/platform/gstreamer/common/qgstutils.cpp +++ b/src/multimedia/platform/gstreamer/common/qgstutils.cpp @@ -94,8 +94,8 @@ static QAudioFormat::SampleFormat gstSampleFormatToSampleFormat(const char *fmt) } -/* - Returns audio format for a sample. +/*! + Returns audio format for a sample \a sample. If the buffer doesn't have a valid audio format, an empty QAudioFormat is returned. */ QAudioFormat QGstUtils::audioFormatForSample(GstSample *sample) @@ -127,9 +127,10 @@ QAudioFormat QGstUtils::audioFormatForCaps(QGstCaps caps) } /*! - Builds GstCaps for an audio format. + Builds GstCaps for an audio format \a format. Returns 0 if the audio format is not valid. - Caller must unref GstCaps. + + \note Caller must unreference GstCaps. */ QGstMutableCaps QGstUtils::capsForAudioFormat(const QAudioFormat &format) diff --git a/src/multimedia/platform/qplatformaudiodecoder.cpp b/src/multimedia/platform/qplatformaudiodecoder.cpp index 817e0656f..decb3605e 100644 --- a/src/multimedia/platform/qplatformaudiodecoder.cpp +++ b/src/multimedia/platform/qplatformaudiodecoder.cpp @@ -73,7 +73,7 @@ QPlatformAudioDecoder::QPlatformAudioDecoder(QAudioDecoder *parent) */ /*! - \fn QPlatformAudioDecoder::setSource(const QString &fileName) + \fn QPlatformAudioDecoder::setSource(const QUrl &fileName) Sets the current source to \a fileName. Changing the source will stop any current decoding and discard any buffers. @@ -210,30 +210,6 @@ void QPlatformAudioDecoder::durationChanged(qint64 duration) } /*! - \fn QPlatformAudioDecoder::audioFormat() const - Returns the current audio format of the decoded stream. - - Any buffers returned should have this format. - - \sa setAudioFormat(), formatChanged() -*/ - -/*! - \fn QPlatformAudioDecoder::setAudioFormat(const QAudioFormat &format) - Set the desired audio format for decoded samples to \a format. - - If the decoder does not support this format, \l error() will - be set to \c FormatError. - - If you do not specify a format, the format of the decoded - audio itself will be used. Otherwise, some format conversion - will be applied. - - If you wish to reset the decoded format to that of the original - audio file, you can specify an invalid \a format. -*/ - -/*! \fn QPlatformAudioDecoder::read() Attempts to read a buffer from the decoder, without blocking. Returns invalid buffer if there are no decoded buffers available, or on error. diff --git a/src/multimedia/platform/qplatformcamera.cpp b/src/multimedia/platform/qplatformcamera.cpp index d0bc9fdcf..21a13ea97 100644 --- a/src/multimedia/platform/qplatformcamera.cpp +++ b/src/multimedia/platform/qplatformcamera.cpp @@ -82,64 +82,12 @@ QCameraFormat QPlatformCamera::findBestCameraFormat(const QCameraDevice &camera) } /*! - \fn QPlatformCamera::state() const - - Returns the state of the camera service. - - \sa QCamera::state -*/ - -/*! - \fn QPlatformCamera::setState(QCamera::State state) - - Sets the camera \a state. - - State changes are synchronous and indicate user intention. - - \sa QCamera::State -*/ - -/*! - \fn void QPlatformCamera::stateChanged(QCamera::State state) - - Signal emitted when the camera \a state changes. - - In most cases the state chage is caused by QPlatformCamera::setState(), - but if critical error has occurred the state changes to QCamera::UnloadedState. -*/ - -/*! \fn void QPlatformCamera::error(int error, const QString &errorString) Signal emitted when an error occurs with error code \a error and a description of the error \a errorString. */ -/*! - \fn QPlatformCamera::supportedViewfinderSettings() const - - Returns a list of supported camera viewfinder settings. - - The list is ordered by preference; preferred settings come first. -*/ - -/*! - \fn QPlatformCamera::viewfinderSettings() const - - Returns the viewfinder settings. - - If undefined or unsupported values are passed to QPlatformCamera::setViewfinderSettings(), - this function returns the actual settings used by the camera viewfinder. These may be available - only once the camera is active. -*/ - -/*! - \fn QPlatformCamera::setViewfinderSettings(const QCameraViewfinderSettings &settings) - - Sets the camera viewfinder \a settings. -*/ - - void QPlatformCamera::supportedFeaturesChanged(QCamera::Features f) { if (m_supportedFeatures == f) diff --git a/src/multimedia/platform/qplatformimagecapture.cpp b/src/multimedia/platform/qplatformimagecapture.cpp index f4296c51a..5cfc7e31e 100644 --- a/src/multimedia/platform/qplatformimagecapture.cpp +++ b/src/multimedia/platform/qplatformimagecapture.cpp @@ -113,12 +113,6 @@ QPlatformImageCapture::QPlatformImageCapture(QImageCapture *parent) */ /*! - \fn QPlatformImageCapture::cancelCapture() - - Cancel pending capture requests. -*/ - -/*! \fn QPlatformImageCapture::imageExposed(int requestId) Signals that an image with it \a requestId diff --git a/src/multimedia/platform/qplatformmediaencoder.cpp b/src/multimedia/platform/qplatformmediaencoder.cpp index bb6397224..7a4707895 100644 --- a/src/multimedia/platform/qplatformmediaencoder.cpp +++ b/src/multimedia/platform/qplatformmediaencoder.cpp @@ -134,19 +134,13 @@ void QPlatformMediaEncoder::resume() { /*! - \fn void QPlatformMediaEncoder::applySettings() + \fn QPlatformMediaEncoder::applySettings(const QMediaEncoderSettings &) Commits the encoder settings and performs pre-initialization to reduce delays when recording is started. */ /*! - \fn bool QPlatformMediaEncoder::isMuted() const - - Returns true if the recorder is muted, and false if it is not. -*/ - -/*! \fn void QPlatformMediaEncoder::stateChanged(QMediaRecorder::RecorderState state) Signals that the \a state of a media recorder has changed. @@ -186,7 +180,7 @@ void QPlatformMediaEncoder::actualLocationChanged(const QUrl &location) } /*! - \fn void QPlatformMediaEncoder::error(int error, const QString &errorString) + \fn void QPlatformMediaEncoder::error(QMediaRecorder::Error error, const QString &errorString) Signals that an \a error has occurred. The \a errorString describes the error. */ diff --git a/src/multimedia/platform/qplatformvideosink.cpp b/src/multimedia/platform/qplatformvideosink.cpp index 2912b32e4..3ac5d38d0 100644 --- a/src/multimedia/platform/qplatformvideosink.cpp +++ b/src/multimedia/platform/qplatformvideosink.cpp @@ -50,15 +50,6 @@ QT_BEGIN_NAMESPACE \ingroup multimedia_control \brief The QPlatformVideoSink class provides a media control for rendering video to a window. - - The winId() property QPlatformVideoSink allows a platform specific window - ID to be set as the video render target. The - displayRect() property is used to set the region of the window the video - should be rendered to, and the aspectRatioMode() property indicates how the - video should be scaled to fit the displayRect(). - - \snippet multimedia-snippets/video.cpp Video window control - QPlatformVideoSink is one of a number of possible video output controls. \sa QVideoWidget @@ -74,48 +65,23 @@ QPlatformVideoSink::QPlatformVideoSink(QVideoSink *parent) } /*! - \fn QPlatformVideoSink::winId() const - - Returns the ID of the window a video overlay end point renders to. -*/ - -/*! \fn QPlatformVideoSink::setWinId(WId id) Sets the \a id of the window a video overlay end point renders to. */ /*! - \fn QPlatformVideoSink::displayRect() const - Returns the sub-rect of a window where video is displayed. -*/ - -/*! \fn QPlatformVideoSink::setDisplayRect(const QRect &rect) Sets the sub-\a rect of a window where video is displayed. */ /*! - \fn QPlatformVideoSink::isFullScreen() const - - Identifies if a video overlay is a fullScreen overlay. - - Returns true if the video overlay is fullScreen, and false otherwise. -*/ - -/*! \fn QPlatformVideoSink::setFullScreen(bool fullScreen) Sets whether a video overlay is a \a fullScreen overlay. */ /*! - \fn QPlatformVideoSink::repaint() - - Repaints the last frame. -*/ - -/*! \fn QPlatformVideoSink::nativeSize() const Returns a suggested size for the video display based on the resolution and aspect ratio of the @@ -130,12 +96,6 @@ QPlatformVideoSink::QPlatformVideoSink(QVideoSink *parent) /*! - \fn QPlatformVideoSink::aspectRatioMode() const - - Returns how video is scaled to fit the display region with respect to its aspect ratio. -*/ - -/*! \fn QPlatformVideoSink::setAspectRatioMode(Qt::AspectRatioMode mode) Sets the aspect ratio \a mode which determines how video is scaled to the fit the display region diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp index 39f3d2f83..c8a81d09e 100644 --- a/src/multimedia/playback/qmediaplayer.cpp +++ b/src/multimedia/playback/qmediaplayer.cpp @@ -684,7 +684,7 @@ QVideoSink *QMediaPlayer::videoSink() const #if 0 -/*! +/* \since 5.15 Sets multiple video sinks as the video output of a media player. This allows the media player to render video frames on several outputs. @@ -726,7 +726,7 @@ QMediaMetaData QMediaPlayer::metaData() const // Enums /*! - \enum QMediaPlayer::State + \enum QMediaPlayer::PlaybackState Defines the current state of a media player. @@ -771,20 +771,15 @@ QMediaMetaData QMediaPlayer::metaData() const // Signals /*! - \fn QMediaPlayer::error(QMediaPlayer::Error error) + \fn QMediaPlayer::errorOccurred(QMediaPlayer::Error error, const QString &errorString) - Signals that an \a error condition has occurred. + Signals that an \a error condition has occurred, with \a errorString + containing a description of the error. \sa errorString() */ /*! - \fn void QMediaPlayer::stateChanged(State state) - - Signal the \a state of the Player object has changed. -*/ - -/*! \fn QMediaPlayer::mediaStatusChanged(QMediaPlayer::MediaStatus status) Signals that the \a status of the current media has changed. @@ -793,19 +788,9 @@ QMediaMetaData QMediaPlayer::metaData() const */ /*! - \fn void QMediaPlayer::mediaChanged(const QUrl &media); + \fn void QMediaPlayer::sourceChanged(const QUrl &media); Signals that the media source has been changed to \a media. - - \sa media(), currentMediaChanged() -*/ - -/*! - \fn void QMediaPlayer::currentMediaChanged(const QUrl &media); - - Signals that the current playing content has been changed to \a media. - - \sa currentMedia(), mediaChanged() */ /*! @@ -822,15 +807,6 @@ QMediaMetaData QMediaPlayer::metaData() const // Properties /*! - \property QMediaPlayer::state - \brief the media player's playback state. - - By default this property is QMediaPlayer::Stopped - - \sa mediaStatus(), play(), pause(), stop() -*/ - -/*! \property QMediaPlayer::error \brief a string describing the last error condition. @@ -838,7 +814,7 @@ QMediaMetaData QMediaPlayer::metaData() const */ /*! - \property QMediaPlayer::media + \property QMediaPlayer::source \brief the active media source being used by the player object. The player object will use the QUrl for selection of the content to @@ -899,22 +875,21 @@ QMediaMetaData QMediaPlayer::metaData() const */ /*! - \property QMediaPlayer::audioAvailable + \property QMediaPlayer::hasAudio \brief the audio availabilty status for the current media. - As the life time of QMediaPlayer can be longer than the playback of one - QUrl, this property may change over time, the - audioAvailableChanged signal can be used to monitor it's status. + \note As the life time of QMediaPlayer can be longer than the playback of + one QUrl, this property may change over time. */ /*! - \property QMediaPlayer::videoAvailable + \property QMediaPlayer::hasVideo \brief the video availability status for the current media. - If available, the QVideoWidget class can be used to view the video. As the - life time of QMediaPlayer can be longer than the playback of one - QUrl, this property may change over time, the - videoAvailableChanged signal can be used to monitor it's status. + If available, the QVideoWidget class can be used to view the video. + + \note As the life time of QMediaPlayer can be longer than the playback of + one QUrl, this property may change over time. \sa QVideoWidget, QUrl */ @@ -957,13 +932,13 @@ QMediaMetaData QMediaPlayer::metaData() const */ /*! - \fn void QMediaPlayer::videoAvailableChanged(bool videoAvailable) + \fn void QMediaPlayer::hasVideoChanged(bool videoAvailable) Signal the availability of visual content has changed to \a videoAvailable. */ /*! - \fn void QMediaPlayer::audioAvailableChanged(bool available) + \fn void QMediaPlayer::hasAudioChanged(bool available) Signals the availability of audio content has changed to \a available. */ diff --git a/src/multimedia/qmediaformat.cpp b/src/multimedia/qmediaformat.cpp index fd049679d..4cd66143a 100644 --- a/src/multimedia/qmediaformat.cpp +++ b/src/multimedia/qmediaformat.cpp @@ -127,19 +127,33 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QMediaFormatPrivate); /*! \enum QMediaFormat::FileFormat Describes the container format used in a multimedia file or stream. + + //! TODO document each \value + + \omitvalue LastFileFormat */ /*! \enum QMediaFormat::AudioCodec Describes the audio coded used in multimedia file or stream. + + //! TODO document each \value + + \omitvalue LastAudioCodec */ -/*! \enum QMediaFormat::AudioCodec +/*! \enum QMediaFormat::VideoCodec Describes the video coded used in multimedia file or stream. + + //! TODO document each \value + + \omitvalue LastVideoCodec */ /*! \class QMediaFormat + \inmodule QtMultimedia + \since 6.2 Describes an encoding format for a multimedia file or stream. @@ -182,18 +196,26 @@ QMediaFormat &QMediaFormat::operator=(const QMediaFormat &other) noexcept = defa Moves \a other into this QMediaFormat objects. */ -/*! \fn void QMediaFormat::setMediaContainer(QMediaFormat::FileFormat container) +// Properties +/*! \property QMediaFormat::fileFormat - Sets the container to \a container. + \brief The file (container) format of the media. - \sa mediaContainer(), QMediaFormat::FileFormat + \sa QMediaFormat::FileFormat */ -/*! \fn QMediaFormat::FileFormat QMediaFormat::mediaContainer() const +/*! \property QMediaFormat::audioCodec - Returns the container used in this format. + \brief The audio codec of the media. - \sa setMediaContainer(), QMediaFormat::FileFormat + \sa QMediaFormat::AudioCodec +*/ + +/*! \property QMediaFormat::videoCodec + + \brief The video codec of the media. + + \sa QMediaFormat::VideoCodec */ /*! \fn void QMediaFormat::setVideoCodec(VideoCodec codec) @@ -224,11 +246,6 @@ QMediaFormat &QMediaFormat::operator=(const QMediaFormat &other) noexcept = defa \sa setAudioCodec(), QMediaFormat::AudioCodec */ -/*! \fn bool QMediaFormat::isValid() const - - Returns true if the format is valid. -*/ - /*! Returns true if Qt Multimedia can encode or decode this format, depending on \a mode. diff --git a/src/multimedia/qmediatimerange.cpp b/src/multimedia/qmediatimerange.cpp index 0b2929c27..80ab5d928 100644 --- a/src/multimedia/qmediatimerange.cpp +++ b/src/multimedia/qmediatimerange.cpp @@ -559,7 +559,6 @@ bool QMediaTimeRange::contains(qint64 time) const /*! \fn bool QMediaTimeRange::operator==(const QMediaTimeRange &lhs, const QMediaTimeRange &rhs) - \relates QMediaTimeRange Returns true if all intervals in \a lhs are present in \a rhs. */ @@ -571,13 +570,15 @@ bool QMediaTimeRange::contains(qint64 time) const */ /*! - \fn QMediaTimeRange QMediaTimeRange::operator+(const QMediaTimeRange &r1, const QMediaTimeRange &r2) + \fn QMediaTimeRange operator+(const QMediaTimeRange &r1, const QMediaTimeRange &r2) + \relates QMediaTimeRange Returns a time range containing the union between \a r1 and \a r2. */ /*! - \fn QMediaTimeRange QMediaTimeRange::operator-(const QMediaTimeRange &r1, const QMediaTimeRange &r2) + \fn QMediaTimeRange operator-(const QMediaTimeRange &r1, const QMediaTimeRange &r2) + \relates QMediaTimeRange Returns a time range containing \a r2 subtracted from \a r1. */ diff --git a/src/multimedia/recording/qmediarecorder.cpp b/src/multimedia/recording/qmediarecorder.cpp index 194440792..c4bc032bd 100644 --- a/src/multimedia/recording/qmediarecorder.cpp +++ b/src/multimedia/recording/qmediarecorder.cpp @@ -172,9 +172,7 @@ void QMediaRecorder::setCaptureSession(QMediaCaptureSession *session) */ /*! - Returns true if media recorder service ready to use. - - \sa availabilityChanged() + Returns \c true if media recorder service ready to use. */ bool QMediaRecorder::isAvailable() const { @@ -331,7 +329,7 @@ void QMediaRecorder::stop() */ /*! - \property QMediaRecorder::RecorderState + \property QMediaRecorder::recorderState \brief The current state of the media recorder. The state property represents the user request and is changed synchronously @@ -340,7 +338,7 @@ void QMediaRecorder::stop() */ /*! - \fn QMediaRecorder::recorderStateChanged(State state) + \fn QMediaRecorder::recorderStateChanged(QMediaRecorder::RecorderState state) Signals that a media recorder's \a state has changed. */ @@ -359,21 +357,10 @@ void QMediaRecorder::stop() */ /*! - \fn QMediaRecorder::error(QMediaRecorder::Error error) - - Signals that an \a error has occurred. -*/ - -/*! - \fn QMediaRecorder::availabilityChanged(bool available) - - Signals that the media recorder is now available (if \a available is true), or not. -*/ - -/*! - \fn QMediaRecorder::mutedChanged(bool muted) + \fn QMediaRecorder::errorOccurred(QMediaRecorder::Error error, const QString &errorString) - Signals that the \a muted state has changed. If true the recording is being muted. + Signals that an \a error has occurred, with \a errorString containing + a description of the error. */ /*! @@ -426,7 +413,7 @@ QMediaCaptureSession *QMediaRecorder::captureSession() const } /*! - \enum QMediaRecorder::EncodingQuality + \enum QMediaRecorder::Quality Enumerates quality encoding levels. diff --git a/src/multimedia/video/qabstractvideobuffer.cpp b/src/multimedia/video/qabstractvideobuffer.cpp index db43beb81..e58e3c264 100644 --- a/src/multimedia/video/qabstractvideobuffer.cpp +++ b/src/multimedia/video/qabstractvideobuffer.cpp @@ -127,14 +127,6 @@ QVideoFrame::HandleType QAbstractVideoBuffer::handleType() const return m_type; } -/*! - \fn QVideoFrame::mapMode() const - - Returns the mode a video buffer is mapped in. - - \sa map() -*/ - /*! \fn uchar *QAbstractVideoBuffer::map(MapMode mode, int *numBytes, int *bytesPerLine) Independently maps the planes of a video buffer to memory. @@ -181,7 +173,7 @@ QVideoFrame::HandleType QAbstractVideoBuffer::handleType() const \sa handleType() */ -/*! +/* \fn int QAbstractPlanarVideoBuffer::map(MapMode mode, int *numBytes, int bytesPerLine[4], uchar *data[4]) Maps the contents of a video buffer to memory. |