Skip to content
Snippets Groups Projects
Commit 24947c36 authored by Philippe Gorley's avatar Philippe Gorley Committed by Sébastien Blin
Browse files

doc: fix doxygen comments

Change-Id: I5e7a776221b2048692966b20ff270a2d8fea8bbf
parent 79354e7c
No related branches found
No related tags found
No related merge requests found
...@@ -34,7 +34,7 @@ struct SwrContext; ...@@ -34,7 +34,7 @@ struct SwrContext;
namespace jami { namespace jami {
/** /**
* Wrapper class for libswresample * @brief Wrapper class for libswresample
*/ */
class Resampler { class Resampler {
public: public:
...@@ -42,36 +42,49 @@ public: ...@@ -42,36 +42,49 @@ public:
~Resampler(); ~Resampler();
/** /**
* @brief Resample a frame.
*
* Resample from @input format to @output format. * Resample from @input format to @output format.
*
* NOTE: sample_rate, channel_layout, and format should be set on @output * NOTE: sample_rate, channel_layout, and format should be set on @output
*/ */
int resample(const AVFrame* input, AVFrame* output); int resample(const AVFrame* input, AVFrame* output);
/** /**
* Wrappers around resample(AVFrame*, AVFrame*) for convenience. * @brief Wrapper around resample(AVFrame*, AVFrame*) for convenience.
*/ */
void resample(const AudioBuffer& dataIn, AudioBuffer& dataOut); void resample(const AudioBuffer& dataIn, AudioBuffer& dataOut);
/**
* @brief Wrapper around resample(AVFrame*, AVFrame*) for convenience.
*/
std::unique_ptr<AudioFrame> resample(std::unique_ptr<AudioFrame>&& in, const AudioFormat& out); std::unique_ptr<AudioFrame> resample(std::unique_ptr<AudioFrame>&& in, const AudioFormat& out);
/**
* @brief Wrapper around resample(AVFrame*, AVFrame*) for convenience.
*/
std::shared_ptr<AudioFrame> resample(std::shared_ptr<AudioFrame>&& in, const AudioFormat& out); std::shared_ptr<AudioFrame> resample(std::shared_ptr<AudioFrame>&& in, const AudioFormat& out);
private: private:
NON_COPYABLE(Resampler); NON_COPYABLE(Resampler);
/** /**
* @brief Reinitializes filter according to new format.
*
* Reinitializes the resampler when new settings are detected. As long as both input and * Reinitializes the resampler when new settings are detected. As long as both input and
* output formats don't change, this will only be called once. * output formats don't change, this will only be called once.
*/ */
void reinit(const AVFrame* in, const AVFrame* out); void reinit(const AVFrame* in, const AVFrame* out);
/** /**
* Libswresample resampler context. * @brief Libswresample resampler context.
* *
* NOTE SwrContext is an imcomplete type and cannot be stored in a smart pointer. * NOTE SwrContext is an imcomplete type and cannot be stored in a smart pointer.
*/ */
SwrContext* swrCtx_; SwrContext* swrCtx_;
/** /**
* Number of times @swrCtx_ has been initialized with no successful audio resampling. * @brief Number of times @swrCtx_ has been initialized with no successful audio resampling.
* *
* 0: Uninitialized * 0: Uninitialized
* 1: Initialized * 1: Initialized
......
...@@ -37,7 +37,7 @@ struct AVFilterInOut; ...@@ -37,7 +37,7 @@ struct AVFilterInOut;
namespace jami { namespace jami {
/** /**
* Provides access to libavfilter. * @brief Provides access to libavfilter.
* *
* Can be used for filters with unlimited number of inputs. * Can be used for filters with unlimited number of inputs.
* Multiple outputs are not supported. They add complexity for little gain. * Multiple outputs are not supported. They add complexity for little gain.
...@@ -64,36 +64,38 @@ class MediaFilter { ...@@ -64,36 +64,38 @@ class MediaFilter {
~MediaFilter(); ~MediaFilter();
/** /**
* Returns the current filter graph string. * @brief Returns the current filter graph string.
*/ */
std::string getFilterDesc() const; std::string getFilterDesc() const;
/** /**
* Initializes the filter graph with one or more inputs and one output. Returns a negative code on error. * @brief Initializes the filter graph with one or more inputs and one output. Returns a negative code on error.
*/ */
int initialize(const std::string& filterDesc, std::vector<MediaStream> msps); int initialize(const std::string& filterDesc, std::vector<MediaStream> msps);
/** /**
* Returns a MediaStream object describing the input specified by @inputName. * @brief Returns a MediaStream object describing the input specified by @inputName.
*/ */
MediaStream getInputParams(const std::string& inputName) const; MediaStream getInputParams(const std::string& inputName) const;
/** /**
* Returns a MediaStream struct describing the frames that will be output. * @brief Returns a MediaStream struct describing the frames that will be output.
* *
* When called in an invalid state, the returned format will be invalid (less than 0). * When called in an invalid state, the returned format will be invalid (less than 0).
*/ */
MediaStream getOutputParams() const; MediaStream getOutputParams() const;
/** /**
* Give the specified source filter an input frame. Caller is responsible for freeing the frame. * @brief Give the specified source filter an input frame.
*
* Caller is responsible for freeing the frame.
* *
* NOTE Will fail if @inputName is not found in the graph. * NOTE Will fail if @inputName is not found in the graph.
*/ */
int feedInput(AVFrame* frame, const std::string& inputName); int feedInput(AVFrame* frame, const std::string& inputName);
/** /**
* Pull a frame from the filter graph. Caller owns the frame reference. * @brief Pull a frame from the filter graph. Caller owns the frame reference.
* *
* Returns AVERROR(EAGAIN) if filter graph requires more input. * Returns AVERROR(EAGAIN) if filter graph requires more input.
* *
...@@ -102,7 +104,7 @@ class MediaFilter { ...@@ -102,7 +104,7 @@ class MediaFilter {
std::unique_ptr<MediaFrame> readOutput(); std::unique_ptr<MediaFrame> readOutput();
/** /**
* Flush filter to indicate EOF. * @brief Flush filter to indicate EOF.
*/ */
void flush(); void flush();
...@@ -110,59 +112,67 @@ class MediaFilter { ...@@ -110,59 +112,67 @@ class MediaFilter {
NON_COPYABLE(MediaFilter); NON_COPYABLE(MediaFilter);
/** /**
* Initializes output of filter graph. * @brief Initializes output of filter graph.
*/ */
int initOutputFilter(AVFilterInOut* out); int initOutputFilter(AVFilterInOut* out);
/** /**
* Initializes an input of filter graph. * @brief Initializes an input of filter graph.
*/ */
int initInputFilter(AVFilterInOut* in, MediaStream msp); int initInputFilter(AVFilterInOut* in, MediaStream msp);
/** /**
* Reinitializes the filter graph with @inputParams_, which should be updated beforehand. * @brief Reinitializes the filter graph.
*
* Reinitializes with @inputParams_, which should be updated beforehand.
*/ */
int reinitialize(); int reinitialize();
/** /**
* Convenience method that prints @msg and returns err. * @brief Convenience method that prints @msg and returns err.
* *
* NOTE @msg should not be null. * NOTE @msg should not be null.
*/ */
int fail(std::string msg, int err) const; int fail(std::string msg, int err) const;
/** /**
* Frees resources used by MediaFilter. * @brief Frees resources used by MediaFilter.
*/ */
void clean(); void clean();
/** /**
* Filter graph pointer. * @brief Filter graph pointer.
*/ */
AVFilterGraph* graph_ = nullptr; AVFilterGraph* graph_ = nullptr;
/** /**
* Filter graph output. Corresponds to a buffersink/abuffersink filter. * @brief Filter graph output.
*
* Corresponds to a buffersink/abuffersink filter.
*/ */
AVFilterContext* output_ = nullptr; AVFilterContext* output_ = nullptr;
/** /**
* List of filter graph inputs. Each corresponds to a buffer/abuffer filter. * @brief List of filter graph inputs.
*
* Each corresponds to a buffer/abuffer filter.
*/ */
std::vector<AVFilterContext*> inputs_; std::vector<AVFilterContext*> inputs_;
/** /**
* List of filter graph input parameters. Same order as @inputs_. * @brief List of filter graph input parameters.
*
* Same order as @inputs_.
*/ */
std::vector<MediaStream> inputParams_; std::vector<MediaStream> inputParams_;
/** /**
* Filter graph string. * @brief Filter graph string.
*/ */
std::string desc_ {}; std::string desc_ {};
/** /**
* Flag to know whether or not the filter graph is initialized. * @brief Flag to know whether or not the filter graph is initialized.
*/ */
bool initialized_ {false}; bool initialized_ {false};
}; };
......
...@@ -45,12 +45,14 @@ public: ...@@ -45,12 +45,14 @@ public:
~MediaRecorder(); ~MediaRecorder();
/** /**
* Gets whether or not the recorder is active. * @brief Gets whether or not the recorder is active.
*/ */
bool isRecording() const; bool isRecording() const;
/** /**
* Get file path of file to be recorded. Same path as sent to @setPath, but with * @brief Get file path of file to be recorded.
*
* Same path as sent to @setPath, but with
* file extension appended. * file extension appended.
* *
* NOTE @audioOnly must be called to have the right extension. * NOTE @audioOnly must be called to have the right extension.
...@@ -58,20 +60,24 @@ public: ...@@ -58,20 +60,24 @@ public:
std::string getPath() const; std::string getPath() const;
/** /**
* @brief Resulting file will be audio or video.
*
* Sets whether or not output file will have audio. Determines the extension of the * Sets whether or not output file will have audio. Determines the extension of the
* output file (.ogg or .webm). * output file (.ogg or .webm).
*/ */
void audioOnly(bool audioOnly); void audioOnly(bool audioOnly);
/** /**
* Sets output file path. * @brief Sets output file path.
* *
* NOTE An empty path will put the output file in the working directory. * NOTE An empty path will put the output file in the working directory.
*/ */
void setPath(const std::string& path); void setPath(const std::string& path);
/** /**
* Sets title and description metadata for the file. Uses default if either is empty. * @brief Sets title and description metadata for the file.
*
* Uses default if either is empty.
* Default title is "Conversation at %Y-%m-%d %H:%M:%S". * Default title is "Conversation at %Y-%m-%d %H:%M:%S".
* Default description is "Recorded with Jami https://jami.net". * Default description is "Recorded with Jami https://jami.net".
* *
...@@ -80,23 +86,30 @@ public: ...@@ -80,23 +86,30 @@ public:
void setMetadata(const std::string& title, const std::string& desc); void setMetadata(const std::string& title, const std::string& desc);
/** /**
* Adds a stream to the recorder. Caller must then attach this to the media source. * @brief Adds a stream to the recorder.
*
* Caller must then attach this to the media source.
*/ */
Observer<std::shared_ptr<MediaFrame>>* addStream(const MediaStream& ms); Observer<std::shared_ptr<MediaFrame>>* addStream(const MediaStream& ms);
/** /**
* Gets the stream observer so the caller can detach it from the media source. * @brief Gets the stream observer.
*
* This is so the caller can detach it from the media source.
*/ */
Observer<std::shared_ptr<MediaFrame>>* getStream(const std::string& name) const; Observer<std::shared_ptr<MediaFrame>>* getStream(const std::string& name) const;
/** /**
* Starts the record. Streams must have been added using Observable::attach and * @brief Initializes the file.
* @addStream. *
* Streams must have been added using Observable::attach and @addStream.
*/ */
int startRecording(); int startRecording();
/** /**
* Stops the record. Streams must be removed using Observable::detach afterwards. * @brief Finalizes the file.
*
* Streams must be removed using Observable::detach afterwards.
*/ */
void stopRecording(); void stopRecording();
......
...@@ -34,69 +34,81 @@ extern "C" { ...@@ -34,69 +34,81 @@ extern "C" {
namespace jami { namespace video { namespace jami { namespace video {
/** /**
* Provides an abstraction layer to the hardware acceleration APIs in FFmpeg. * @brief Provides an abstraction layer to the hardware acceleration APIs in FFmpeg.
*/ */
class HardwareAccel { class HardwareAccel {
public: public:
/** /**
* Static factory method for hardware decoding. * @brief Static factory method for hardware decoding.
*/ */
static std::unique_ptr<HardwareAccel> setupDecoder(AVCodecID id, int width, int height); static std::unique_ptr<HardwareAccel> setupDecoder(AVCodecID id, int width, int height);
/** /**
* Static factory method for hardware encoding. * @brief Static factory method for hardware encoding.
*/ */
static std::unique_ptr<HardwareAccel> setupEncoder(AVCodecID id, int width, int height, static std::unique_ptr<HardwareAccel> setupEncoder(AVCodecID id, int width, int height,
AVBufferRef* framesCtx = nullptr); AVBufferRef* framesCtx = nullptr);
/** /**
* @brief Transfers hardware frame to main memory.
*
* Transfers a hardware decoded frame back to main memory. Should be called after * Transfers a hardware decoded frame back to main memory. Should be called after
* the frame is decoded using avcodec_send_packet/avcodec_receive_frame. * the frame is decoded using avcodec_send_packet/avcodec_receive_frame.
* *
* @frame: Refrerence to the decoded hardware frame. * If @frame is software, this is a no-op.
* @returns: Software frame. *
* @param frame Refrerence to the decoded hardware frame.
* @param desiredFormat Software pixel format that the hardware outputs.
* @returns Software frame.
*/ */
static std::unique_ptr<VideoFrame> transferToMainMemory(const VideoFrame& frame, AVPixelFormat desiredFormat); static std::unique_ptr<VideoFrame> transferToMainMemory(const VideoFrame& frame, AVPixelFormat desiredFormat);
/** /**
* @brief Constructs a HardwareAccel object
*
* Made public so std::unique_ptr can access it. Should not be called. * Made public so std::unique_ptr can access it. Should not be called.
*/ */
HardwareAccel(AVCodecID id, const std::string& name, AVHWDeviceType hwType, AVPixelFormat format, AVPixelFormat swFormat, CodecType type); HardwareAccel(AVCodecID id, const std::string& name, AVHWDeviceType hwType, AVPixelFormat format, AVPixelFormat swFormat, CodecType type);
/** /**
* Dereferences hardware contexts. * @brief Dereferences hardware contexts.
*/ */
~HardwareAccel(); ~HardwareAccel();
/** /**
* Codec that is being accelerated. * @brief Codec that is being accelerated.
*/ */
AVCodecID getCodecId() const { return id_; }; AVCodecID getCodecId() const { return id_; };
/** /**
* Name of the hardware layer/API being used. * @brief Name of the hardware layer/API being used.
*/ */
std::string getName() const { return name_; }; std::string getName() const { return name_; };
/** /**
* Hardware format. * @brief Hardware format.
*/ */
AVPixelFormat getFormat() const { return format_; }; AVPixelFormat getFormat() const { return format_; };
/** /**
* Software format. For encoding it is the format expected by the hardware. For decoding * @brief Software format.
*
* For encoding it is the format expected by the hardware. For decoding
* it is the format output by the hardware. * it is the format output by the hardware.
*/ */
AVPixelFormat getSoftwareFormat() const { return swFormat_; } AVPixelFormat getSoftwareFormat() const { return swFormat_; }
/** /**
* Gets the name of the codec. * @brief Gets the name of the codec.
*
* Decoding: avcodec_get_name(id_) * Decoding: avcodec_get_name(id_)
* Encoding: avcodec_get_name(id_) + '_' + name_ * Encoding: avcodec_get_name(id_) + '_' + name_
*/ */
std::string getCodecName() const; std::string getCodecName() const;
/** /**
* @brief If hardware decoder can feed hardware encoder directly.
*
* Returns whether or not the decoder is linked to an encoder or vice-versa. Being linked * Returns whether or not the decoder is linked to an encoder or vice-versa. Being linked
* means an encoder can directly use the decoder's hardware frame, without first * means an encoder can directly use the decoder's hardware frame, without first
* transferring it to main memory. * transferring it to main memory.
...@@ -104,7 +116,9 @@ public: ...@@ -104,7 +116,9 @@ public:
bool isLinked() const { return linked_; } bool isLinked() const { return linked_; }
/** /**
* Set some extra details in the codec context. Should be called after a successful * @brief Set some extra details in the codec context.
*
* Should be called after a successful
* setup (setupDecoder or setupEncoder). * setup (setupDecoder or setupEncoder).
* For decoding, sets the hw_device_ctx and get_format callback. If the decoder has * For decoding, sets the hw_device_ctx and get_format callback. If the decoder has
* a frames context, mark as linked. * a frames context, mark as linked.
...@@ -114,18 +128,21 @@ public: ...@@ -114,18 +128,21 @@ public:
void setDetails(AVCodecContext* codecCtx); void setDetails(AVCodecContext* codecCtx);
/** /**
* @brief Transfers a frame to/from the GPU memory.
*
* Transfers a hardware decoded frame back to main memory. Should be called after * Transfers a hardware decoded frame back to main memory. Should be called after
* the frame is decoded using avcodec_send_packet/avcodec_receive_frame or before * the frame is decoded using avcodec_send_packet/avcodec_receive_frame or before
* the frame is encoded using avcodec_send_frame/avcodec_receive_packet. * the frame is encoded using avcodec_send_frame/avcodec_receive_packet.
* *
* @frame: Hardware frame when decoding, software frame when encoding. * @param frame Hardware frame when decoding, software frame when encoding.
* @returns: Software frame when decoding, hardware frame when encoding. * @returns Software frame when decoding, hardware frame when encoding.
*/ */
std::unique_ptr<VideoFrame> transfer(const VideoFrame& frame); std::unique_ptr<VideoFrame> transfer(const VideoFrame& frame);
/** /**
* Links this HardwareAccel's frames context with the passed in context. This serves * @brief Links this HardwareAccel's frames context with the passed in context.
* to skip transferring a decoded frame back to main memory before encoding. *
* This serves to skip transferring a decoded frame back to main memory before encoding.
*/ */
bool linkHardware(AVBufferRef* framesCtx); bool linkHardware(AVBufferRef* framesCtx);
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment