Add some high level function documentation
Added more high level function documentation.
BUG=aomedia:2674
Change-Id: I090d24a00014f916b9a18bf33f279edf7463f87c
diff --git a/av1/encoder/encode_strategy.h b/av1/encoder/encode_strategy.h
index 10bffdb..07616f8 100644
--- a/av1/encoder/encode_strategy.h
+++ b/av1/encoder/encode_strategy.h
@@ -23,9 +23,23 @@
#include "av1/encoder/encoder.h"
#include "av1/encoder/firstpass.h"
-// This function will implement high-level encode strategy, choosing frame type,
-// frame placement, etc. It populates an EncodeFrameParams struct with the
-// results of these decisions and then calls av1_encode()
+/*!\brief Implement high-level encode strategy
+ * \ingroup high_level_algo
+ * This function will implement high-level encode strategy, choosing frame type,
+ * frame placement, etc. It populates an EncodeFrameParams struct with the
+ * results of these decisions and then calls av1_encode().
+ *
+ * \param[in] cpi Top-level encoder structure
+ * \param[in] size Bitstream size
+ * \param[in] dest Bitstream output
+ * \param[in] frame_flags Flags to decide how to encoding the frame
+ * \param[in] time_stamp Time stamp of the frame
+ * \param[in] time_end Time end
+ * \param[in] timestamp_ratio Time base
+ * \param[in] flush Decide to encode one frame or the rest of frames
+ *
+ * \return Returns a value to indicate if the encoding is done successfully.
+ */
int av1_encode_strategy(AV1_COMP *const cpi, size_t *const size,
uint8_t *const dest, unsigned int *frame_flags,
int64_t *const time_stamp, int64_t *const time_end,
diff --git a/av1/encoder/encoder.h b/av1/encoder/encoder.h
index 15e2744..ed669cf 100644
--- a/av1/encoder/encoder.h
+++ b/av1/encoder/encoder.h
@@ -1640,16 +1640,30 @@
int subsampling_x, int subsampling_y);
/*!\endcond */
-// receive a frames worth of data. caller can assume that a copy of this
-// frame is made and not just a copy of the pointer..
+/*!\brief Obtain the raw frame data
+ * \ingroup high_level_algo
+ * This function receives the raw frame data from input.
+ *
+ * \param[in] cpi Top-level encoder structure
+ * \param[in] frame_flags Flags to decide how to encoding the frame
+ * \param[in] sd Contain raw frame data
+ * \param[in] time_stamp Time stamp of the frame
+ * \param[in] end_time_stamp End time stamp
+ *
+ * \return Returns a value to indicate if the frame data is received
+ * successfully.
+ * \note The caller of this function is the encoder interface: encoder_encode().
+ * The caller can assume that a copy of this frame is made and not just a
+ * copy of the pointer.
+ */
int av1_receive_raw_frame(AV1_COMP *cpi, aom_enc_frame_flags_t frame_flags,
YV12_BUFFER_CONFIG *sd, int64_t time_stamp,
int64_t end_time_stamp);
/*!\brief Encode a frame
* \ingroup high_level_algo
- * This function receives a raw frame, and encode that frame. It outputs the
- * frame bit stream to the designated buffer.
+ * This function encodes the raw frame data, and outputs the frame bit stream
+ * to the designated buffer.
*
* \param[in] cpi Top-level encoder structure
* \param[in] frame_flags Flags to decide how to encoding the frame
@@ -1661,8 +1675,8 @@
* \param[in] timebase Time base used
*
* \return Returns a value to indicate if the encoding is done successfully.
- * \note A note for this function.
- * \warning A warning message for this function.
+ * \note Main entry point of encoding a frame. The caller of this function is
+ * the encoder interface: encoder_encode().
*/
int av1_get_compressed_data(AV1_COMP *cpi, unsigned int *frame_flags,
size_t *size, uint8_t *dest, int64_t *time_stamp,
diff --git a/doc/dev_guide/av1_encoder.dox b/doc/dev_guide/av1_encoder.dox
index 8bf42e0..af0c5e0 100644
--- a/doc/dev_guide/av1_encoder.dox
+++ b/doc/dev_guide/av1_encoder.dox
@@ -2,6 +2,9 @@
AV1 encoding algorithm consists following modules:
- \ref high_level_algo
+ - To encode a frame, first call \ref av1_receive_raw_frame() to obtain the
+ raw frame data. Then call \ref av1_get_compressed_data() to encode raw
+ frame data into compressed frame data.
- \ref partition_search
- \ref intra_mode_search
- \ref inter_mode_search
@@ -9,9 +12,6 @@
- \ref in_loop_filter
- \ref rate_control
- Encode a frame
- - To encode a frame, call \ref av1_get_compressed_data().
-
<b>[SAMPLE CONTEXT ONLY - copied from AV1 overview paper]:</b>
In this paper, we present the core coding tools in AV1 that contribute to
diff --git a/docs.cmake b/docs.cmake
index 5fdc3d3..e8b6136 100644
--- a/docs.cmake
+++ b/docs.cmake
@@ -101,7 +101,8 @@
set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES}
"${AOM_ROOT}/doc/dev_guide/av1_encoder.dox")
set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES}
- "${AOM_ROOT}/av1/encoder/encoder.h")
+ "${AOM_ROOT}/av1/encoder/encoder.h"
+ "${AOM_ROOT}/av1/encoder/encode_strategy.h")
endif()
if(CONFIG_AV1_DECODER AND CONFIG_AV1_ENCODER)
