From c746a78b241580df1be00b95c5082c25f2903e07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=AD=90=E5=BE=AE?= Date: Wed, 13 Nov 2024 16:39:58 +0800 Subject: [PATCH 1/6] =?UTF-8?q?[interface=5Fsdk]=20=E4=BF=AE=E6=94=B9video?= =?UTF-8?q?encder=E5=92=8C=5Fcore=E7=9A=84=E8=8B=B1=E6=96=87=E5=A4=B4?= =?UTF-8?q?=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王子微 --- .../av_codec/native_avcodec_videoencoder.h | 181 +++++++++--------- .../native_audio_channel_layout.h | 3 +- multimedia/media_foundation/native_avbuffer.h | 68 ++++--- multimedia/media_foundation/native_averrors.h | 4 + multimedia/media_foundation/native_avformat.h | 146 +++++++++----- multimedia/media_foundation/native_avmemory.h | 8 +- 6 files changed, 238 insertions(+), 172 deletions(-) diff --git a/multimedia/av_codec/native_avcodec_videoencoder.h b/multimedia/av_codec/native_avcodec_videoencoder.h index a0ccb13b6..26028bea0 100644 --- a/multimedia/av_codec/native_avcodec_videoencoder.h +++ b/multimedia/av_codec/native_avcodec_videoencoder.h @@ -46,43 +46,42 @@ extern "C" { #endif /** - * @brief When OH_AVCodec needs new input parameter during the running process, the function pointer will be called and - * carry an available OH_AVFormat to fill in the new input parameter. This parameter takes effect immediately with the - * frame. - * + * @brief Configure frame parameters. This interface can be used to set the encode parameters of the frame corresponding to the index, + * take effect only in Surface mode. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec OH_AVCodec instance - * @param index The index corresponding to the new OH_AVFormat instance - * @param parameter Parameter containing the new OH_AVFormat instance - * @param userData specified data + * @param index The index corresponding to the encode frame + * @param parameter Encode parameter + * @param userData The data that the user rely on to execute the callback * @since 12 */ typedef void (*OH_VideoEncoder_OnNeedInputParameter)(OH_AVCodec *codec, uint32_t index, OH_AVFormat *parameter, void *userData); /** - * @brief Creates a video encoder instance from the mime type, which is recommended in most cases. + * @brief Creates a video encoder instance from the mime type, recommended for use. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} * @return Returns a Pointer to an OH_AVCodec instance. - * Return nullptr if memory ran out or the mime type is not supported. + * Return NULL if memory ran out or the mime type is not supported. * @since 9 */ OH_AVCodec *OH_VideoEncoder_CreateByMime(const char *mime); /** * @brief Create a video encoder instance through the video encoder name. The premise of using this interface is to - * know the exact name of the encoder. + * know the exact name of the encoder. The encoder name can be obtained through capability query. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param name Video encoder name * @return Returns a Pointer to an OH_AVCodec instance. - * Return nullptr if memory ran out or the encoder name is not supported. + * Return NULL if memory ran out or the encoder name is not supported. * @since 9 */ OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); /** - * @brief Clear the internal resources of the encoder and destroy the encoder instance + * @brief Clear the internal resources of the encoder and destroy the encoder instance. + * Can not be destoryed repeatedly. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, @@ -90,24 +89,24 @@ OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); * {@link AV_ERR_NO_MEMORY}, inner resource has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); /** - * @brief Set the asynchronous callback function so that your application can respond to the events generated by the + * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated by the * video encoder. This interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} - * @param userData User specific data + * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, inner resource has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. * @deprecated since 11 * @useinstead OH_VideoEncoder_RegisterCallback @@ -116,38 +115,38 @@ OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); /** - * @brief Set the asynchronous callback function so that your application can respond to the events generated by the + * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated by the * video encoder. This interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} - * @param userData User specific data + * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, inner resource has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. * @since 11 */ OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); /** - * @brief Set the asynchronous callback function so that your application can respond to the events generated by the - * video encoder. This interface is optional only for input surface. If this interface is used, it must be invoked - * before {@link OH_VideoEncoder_Configure}. + * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated by the + * video encoder. In encode Surface mode, this interface is used to set frame-specific parameters. If this interface is used, + * it must be invoked before {@link OH_VideoEncoder_Configure}. * * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param onInputParameter A callback functions, see {@link OH_VideoEncoder_OnNeedInputParameter} - * @param userData User specific data + * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, inner resource has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. * @since 12 */ @@ -156,34 +155,31 @@ OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback(OH_AVCodec *codec, void *userData); /** - * @brief To configure the video encoder, typically, you need to configure the description information of the - * encoded video track. This interface must be called before Prepare is called. + * @brief To configure the encode parameters of video encoder, typically, you need to configure the description information of the + * encoded video track, such as the width, height, and pixel format. This interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param format A pointer to an OH_AVFormat that gives the description of the video track to be encoded * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. Invalid param in format. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. + * {@link AV_ERR_INVALID_VAL}, 1. the encoder is nullptr or invalid; 2. invalid param in format. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); /** - * @brief To prepare the internal resources of the encoder, the Configure interface must be called before + * @brief Prepare the internal resources of the encoder.The Configure interface must be called before * calling this interface. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. - * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); @@ -195,67 +191,67 @@ OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Start(OH_AVCodec *codec); /** - * @brief Stop the encoder. After stopping, you can re-enter the Started state through Start. + * @brief Stop the encoder and release the input and output buffer. After stopping, + * you can re-enter the Executing state through Start. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); /** - * @brief Clear the input and output data buffered in the encoder. After this interface is called, all the Buffer - * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access the - * Buffers corresponding to these indexes. + * @brief Clear the input and output data buffered and parameters in the encoder, for example, PPS/SPS in H264 format. + * After this interface is called, all the buffer indexes previously reported through the asynchronous callback will be + * invalidated, make sure not to access the buffers corresponding to these indexes. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Flush(OH_AVCodec *codec); /** - * @brief Reset the encoder. To continue coding, you need to call the Configure interface again to - * configure the encoder instance. + * @brief Reset the encoder. The encoder returns to the Initialized state. To continue coding, + * you need to call the Configure interface again to configure the encoder instance. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. - * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 */ OH_AVErrCode OH_VideoEncoder_Reset(OH_AVCodec *codec); /** - * @brief Get the description information of the output data of the encoder, refer to {@link OH_AVFormat} for details. + * @brief Get the OH_AVFormat of the output data of the encoder, refer to {@link OH_AVFormat} for details. * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to - * be manually released by the caller. + * be released by {@link OH_AVFormat_Destroy}. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns a pointer to an OH_AVFormat instance. @@ -265,17 +261,17 @@ OH_AVErrCode OH_VideoEncoder_Reset(OH_AVCodec *codec); OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); /** - * @brief Set dynamic parameters to the encoder. Note: This interface can only be called after the encoder is started. + * @brief Set encoder parameters when encoder running. Note: This interface can only be called after the encoder is started. * At the same time, incorrect parameter settings may cause the encoding to fail. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param format OH_AVFormat handle pointer * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. Invalid param in format. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. + * {@link AV_ERR_INVALID_VAL}, 1. the encoder is nullptr or invalid; 2. invalid param in format. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 9 */ @@ -289,11 +285,9 @@ OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format * managing the life cycle of the window, call OH_NativeWindow_DestroyNativeWindow() when done. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, inner resource has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. - * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 */ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **window); @@ -302,14 +296,13 @@ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **wind * @brief Return the processed output Buffer to the encoder. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index The index value corresponding to the output Buffer + * @param index The index value corresponding to the output Buffer, should be given by {@link OH_AVCodecOnNewOutputData} * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * Buffer index should be given by {@link OH_AVCodecOnNewOutputData}. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @deprecated since 11 * @useinstead OH_VideoEncoder_FreeOutputBuffer @@ -318,16 +311,16 @@ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **wind OH_AVErrCode OH_VideoEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); /** - * @brief Notifies the video encoder that the input stream has ended. It is recommended to use this interface to notify - * the encoder of the end of the stream in surface mode + * @brief Notifies the video encoder that the input stream has ended. this interface is only used in Surface mode. + * in Buffer mode, the OH_AVBuffer carries the EOS information to notify the end of the stream. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 9 */ @@ -337,15 +330,14 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); * @brief Submit the input buffer filled with data to the video encoder. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index Enter the index value corresponding to the Buffer + * @param index Enter the index value corresponding to the Buffer, should be given by {@link OH_AVCodecOnNeedInputData}. * @param attr Information describing the data contained in the Buffer * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * Buffer index should be given by {@link OH_AVCodecOnNeedInputData}. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @deprecated since 11 * @useinstead OH_VideoEncoder_PushInputBuffer @@ -354,17 +346,16 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); /** - * @brief Submit the input buffer filled with data to the video encoder. + * @brief In Buffer mode, the OH_AVBuffer corresponding to the index is submited to the encoder for encoding. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index Enter the index value corresponding to the Buffer + * @param index Enter the index value corresponding to the Buffer, should be given by {@link OH_AVCodecOnNeedInputBuffer}. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * Buffer index should be given by {@link OH_AVCodecOnNeedInputBuffer}. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 11 @@ -372,48 +363,53 @@ OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH OH_AVErrCode OH_VideoEncoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); /** - * @brief Submit the input parameter filled with data to the video encoder. - * + * @brief In Surface mode, the encode parameters of the frame corresponding to the index is submited to the encoder for encoding. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index Enter the index value corresponding to the input parameter + * @param index Enter the index value corresponding to the input parameter, + * should be given by {@link OH_VideoEncoder_OnNeedInputParameter} * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * Index should be given by {@link OH_VideoEncoder_OnNeedInputParameter}. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 12 */ OH_AVErrCode OH_VideoEncoder_PushInputParameter(OH_AVCodec *codec, uint32_t index); /** - * @brief Return the processed output Buffer to the encoder. + * @brief Return the OH_AVBuffer corresponding to the processed index to the encoder. + * Need to call this interface to release output buffer immediately after using. + * otherwise, the encode process will be blocked. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index The index value corresponding to the output Buffer + * @param index The index value corresponding to the output buffer, + * should be given by {@link OH_AVCodecOnNewOutputBuffer}. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * Buffer index should be given by {@link OH_AVCodecOnNewOutputBuffer}. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. + * {@link AV_ERR_INVALID_VAL}, + * 1. the encoder is nullptr or invalid; + * 2. invalid param in format; + * 3. the index is vaild or consecutively assigned to the same index, + * the error do not affect the subsequent encode process. * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. + * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. * @since 11 */ OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); /** - * @brief Get the input data description of the encoder after call {@OH_VideoEncoder_Configure}, + * @brief Description information of the image received by the encoder after call {@OH_VideoEncoder_Configure}, * refer to {@link OH_AVFormat} for details. It should be noted that the life cycle of the OH_AVFormat - * instance pointed to by the return value needs to be manually released by the caller. + * instance pointed to by the return value needs to be released by {@link OH_AVFormat_Destroy}. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns a pointer to an OH_AVFormat instance. - * Return nullptr if the encoder is nullptr or invaild. + * Return NULL if the encoder is nullptr or invaild. * @since 10 */ OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); @@ -424,13 +420,10 @@ OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, - * false if the codec instance is invalid + * false if the codec instance is invalid. It is recommend that the invoker initialize isValid to false. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, instance has already released. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. - * {@link AV_ERR_UNKNOWN}, unknown error. - * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. * @since 10 */ OH_AVErrCode OH_VideoEncoder_IsValid(OH_AVCodec *codec, bool *isValid); diff --git a/multimedia/media_foundation/native_audio_channel_layout.h b/multimedia/media_foundation/native_audio_channel_layout.h index 1397d70cd..2b62da800 100644 --- a/multimedia/media_foundation/native_audio_channel_layout.h +++ b/multimedia/media_foundation/native_audio_channel_layout.h @@ -25,8 +25,7 @@ /** * @file native_audio_channel_layout.h * - * @brief The channel layout indicates the appearance and order of the speakers for recording or playback. - * + * @brief The channel layout during recording and playback. * @kit AVCodecKit * @library NA * @syscap SystemCapability.Multimedia.Media.Core diff --git a/multimedia/media_foundation/native_avbuffer.h b/multimedia/media_foundation/native_avbuffer.h index 29ff41d31..fe2b655ec 100644 --- a/multimedia/media_foundation/native_avbuffer.h +++ b/multimedia/media_foundation/native_avbuffer.h @@ -66,15 +66,17 @@ typedef struct OH_NativeBuffer OH_NativeBuffer; * to by the return value * needs to be manually released by {@link OH_AVBuffer_Destroy}. * @syscap SystemCapability.Multimedia.Media.Core * @param capacity the buffer's capacity, bytes - * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns nullptr. - * Possible failure causes: 1. capacity <= 0. 2. create allocator failed. 3. create OH_AVBuffer failed. - * 4. created buffer memory is nullptr. 5. created buffer memory's addr is nullptr. 6. failed to new OH_AVBuffer. + * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns NULL. + * Possible failure causes: + * 1. capacity <= 0; + * 2. internal error occurred, the system has no resources. * @since 11 */ OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); /** * @brief Clear the internal resources of the buffer and destroy the buffer instance. + * The same buffer can not be destroyed repeatedly. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Function result code. @@ -86,54 +88,58 @@ OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); /** - * @brief Get the buffer's attribute. + * @brief Get the buffer's attribute, such as pts, size, offset, and flags. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to * {@link OH_AVCodecBufferAttr} * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, - * input buffer's buffer is nulllptr or attr is nullptr. + * {@link AV_ERR_INVALID_VAL} 1. input buffer or attr is nullptr; 2. buffer's magic error. * @since 11 */ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr); /** - * @brief Set the buffer's attribute. + * @brief Set the buffer's attribute, such as pts, size, offset, and flags. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @param attr Encapsulate OH_AVCodecBufferAttr structure instance pointer, please refer to * {@link OH_AVCodecBufferAttr} * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, - * input buffer's buffer is nulllptr, attr is nullptr, the size or offset of input buffer's memory is invalid. + * {@link AV_ERR_INVALID_VAL} + * 1. input buffer or attr is nullptr; + * 2. buffer's magic error; + * 3. the size or offset of input buffer's memory is invalid. * @since 11 */ OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr); /** - * @brief Get the buffer's parameter. It should be noted that the life cycle of the OH_AVFormat instance pointed to - * by the return value * needs to be manually released by {@link OH_AVFormat_Destroy}. + * @brief Get parameters except basic attributes, the information is carried in OH_AVFormat. + * It should be noted that the life cycle of the OH_AVFormat instance pointed to + * by the return value * needs to be released by {@link OH_AVFormat_Destroy}. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Returns Encapsulate OH_AVFormat structure instance pointer if the execution is successful, - * otherwise returns nullptr. Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. - * 3. input buffer's buffer is nulllptr. 4. buffer's meta is nullptr. + * otherwise returns nullptr. Possible failure causes: + * 1. input buffer is nullptr; + * 2. buffer's magic error; + * 3. buffer's meta is nullptr. * @since 11 */ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); /** - * @brief Set the buffer's parameter. + * @brief Set parameters except basic attributes, the information is carried in OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @param format Encapsulate OH_AVFormat structure instance pointer * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr, buffer's magic error, - * input buffer's buffer is nulllptr, input format is nullptr, buffer's magic error, or input meta is nullptr. + * {@link AV_ERR_INVALID_VAL} 1.input buffer or format is nullptr; 2.buffer's magic error; + * 3.input meta is nullptr. * @since 11 */ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); @@ -142,32 +148,38 @@ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *fo * @brief Get the buffer's virtual address. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return the buffer's virtual address if the buffer is valid, otherwise nullptr - * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. - * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. + * @return the buffer's virtual address if the buffer is valid, otherwise NULL + * Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification error the OH_AVBuffer; + * 3. internal error has occurred. * @since 11 */ uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); /** - * @brief Get the buffer's capacity + * @brief Get the buffer's capacity(byte). * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return the buffer's capacity if the buffer is valid, otherwise -1 - * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. - * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. + * @return The buffer's capacity if the buffer is valid, otherwise -1 + * Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification error the OH_AVBuffer; + * 3. internal error has occurred. * @since 11 */ int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); /** - * @brief Get the OH_NativeBuffer instance pointer,It should be noted that the life cycle of the OH_AVBuffer - * instance pointed to by the return value * needs to be manually released by {@link OH_NativeBuffer_Unreference}. + * @brief Get the OH_NativeBuffer instance pointer. It should be noted that the life cycle of the OH_AVBuffer + * instance pointed to by the return value * needs to be released by {@link OH_NativeBuffer_Unreference}. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer - * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns nullptr - * Possible failure causes: 1. input buffer is nullptr. 2. buffer's magic error. - * 3. input buffer's buffer is nulllptr. 4. buffer's memory is nullptr. 5. surfaceBuffer is nullptr. + * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns NULL + * Possible failure causes: + * 1. input buffer is nullptr; + * 2. structure verification error the OH_AVBuffer; + * 3. internal error has occurred. * @since 11 */ OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer); diff --git a/multimedia/media_foundation/native_averrors.h b/multimedia/media_foundation/native_averrors.h index 80cf8d292..c1c27b7c7 100644 --- a/multimedia/media_foundation/native_averrors.h +++ b/multimedia/media_foundation/native_averrors.h @@ -27,7 +27,11 @@ /** * @file native_averrors.h * +<<<<<<< HEAD * @brief Media framework error code. +======= + * @brief Media framework error description. +>>>>>>> 684c9ac8 ([interface_sdk] 修改videoencder和_core的英文头文件) * * @kit AVCodecKit * @library libnative_media_core.so diff --git a/multimedia/media_foundation/native_avformat.h b/multimedia/media_foundation/native_avformat.h index ac30d2d47..b7f360190 100644 --- a/multimedia/media_foundation/native_avformat.h +++ b/multimedia/media_foundation/native_avformat.h @@ -92,13 +92,13 @@ typedef enum OH_AVPixelFormat { struct OH_AVFormat *OH_AVFormat_Create(void); /** - * @briefCreate an audio OH_AVFormat handle pointer to read and write data + * @briefCreate an audio OH_AVFormat handle pointer to read and write data. * @syscap SystemCapability.Multimedia.Media.Core * @param mimeType mime type * @param sampleRate sample rate * @param channelCount channel count * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr - * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr. + * Possible failure causes: 1. mimeType is nullptr; 2. new format is nullptr. * @since 10 * @version 1.0 */ @@ -107,13 +107,13 @@ struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, int32_t channelCount); /** - * @briefCreate an video OH_AVFormat handle pointer to read and write data + * @brief Create an video OH_AVFormat handle pointer to read and write data. * @syscap SystemCapability.Multimedia.Media.Core * @param mimeType mime type * @param width width * @param height height * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr - * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr. + * Possible failure causes: 1. mimeType is nullptr; 2. new format is nullptr. * @since 10 * @version 1.0 */ @@ -122,7 +122,8 @@ struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, int32_t height); /** - * @brief Destroy the specified OH_AVFormat handle resource + * @brief Destroy the specified OH_AVFormat handle resource. + * Can not be destoryed repeatedly. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @return void @@ -132,164 +133,212 @@ struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, void OH_AVFormat_Destroy(struct OH_AVFormat *format); /** - * @brief Copy OH_AVFormat handle resource + * @brief Copy OH_AVFormat handle resource. * @syscap SystemCapability.Multimedia.Media.Core * @param to OH_AVFormat handle pointer to receive data * @param from pointer to the OH_AVFormat handle of the copied data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. + * Possible failure causes: + * 1. input parameter is nullptr; + * 2. structure verification error of the input OH_AVFormat. * @since 9 * @version 1.0 */ bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); /** - * @brief Write Int data to OH_AVFormat + * @brief Set a value of Int type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); /** - * @brief Write Long data to OH_AVFormat + * @brief Set a value of Long type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); /** - * @brief Write Float data to OH_AVFormat + * @brief Set a value of Float type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); /** - * @brief Write Double data to OH_AVFormat + * @brief Set a value of Double type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); /** - * @brief Write String data to OH_AVFormat + * @brief Set a value of String type to the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data * @param value written data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. value is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input value is nullptr; + * 5. value type corresponding to the key is incorrect; * @since 9 * @version 1.0 */ bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); /** - * @brief Write a block of data of a specified length to OH_AVFormat + * @brief Write a block of data of a specified length to OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key key to write data - * @param addr written data addr - * @param size written data length + * @param addr written data addr, the lifecycle is managed by the invoker + * @param size written data length, range is(0, 1)MB * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. addr is nullptr. 5. size is zero. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input addr is nullptr; + * 5. size is 0 or exceeds the limit by 1MB; + * 6. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 */ bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); /** - * @brief Read Int data from OH_AVFormat + * @brief Get the Int value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. out is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. The obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); /** - * @brief Read Long data from OH_AVFormat + * @brief Get the Long value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. out is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. The obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); /** - * @brief Read Float data from OH_AVFormat + * @brief Get the Float value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. out is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. The obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); /** - * @brief Read Double data from OH_AVFormat + * @brief Get the Double value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out read data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. out is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. The obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); /** - * @brief Read String data from OH_AVFormat + * @brief Get the String value from the key of OH_AVFormat. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @param key read key value * @param out The read string pointer, the data life cycle pointed to is updated with GetString, * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. out is nullptr. 5. malloc out string nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input out is nullptr; + * 5. malloc out string nullptr; + * 6. The obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -299,24 +348,31 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con * @brief Read a block of data of specified length from OH_AVFormat * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance - * @param key Key value for reading and writing data + * @param key Key value for reading data * @param addr The life cycle is held by the format, with the destruction of the format, * if the caller needs to hold it for a long time, it must copy the memory - * @param size Length of read and write data + * @param size Length of read data * @return The return value is TRUE for success, FALSE for failure - * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. - * 4. addr is nullptr. 5. size is nullptr. + * Possible failure causes: + * 1. input format is nullptr; + * 2. structure verification error of the input format; + * 3. input key is nullptr; + * 4. input addr is nullptr; + * 5. input size is nullptr; + * 6. The obtained key does not exist or is not set. * @since 9 * @version 1.0 */ bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); /** - * @brief Output the information contained in OH_AVFormat as a string. + * @brief Return a string consisting of key and values contained in OH_AVFormat. + * the max string that can be returned is 1024 bytes, + * and the string pointer is released when the format is destroyed. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance - * @return Returns a string consisting of key and data for success, nullptr for failure - * Possible failure causes: 1. input format is nullptr. 2. malloc dump info nullptr. + * @return Returns a string consisting of key and data for success, NULL for failure + * Possible failure causes: 1. input format is nullptr; 2. system resources are insufficient. * @since 9 * @version 1.0 */ diff --git a/multimedia/media_foundation/native_avmemory.h b/multimedia/media_foundation/native_avmemory.h index 224f34004..82bfe7981 100644 --- a/multimedia/media_foundation/native_avmemory.h +++ b/multimedia/media_foundation/native_avmemory.h @@ -57,8 +57,10 @@ typedef struct OH_AVMemory OH_AVMemory; * @syscap SystemCapability.Multimedia.Media.Core * @param size the memory's size, bytes. * @return Returns a pointer to an OH_AVMemory instance for success, needs to be freed by OH_AVMemory_Destroy, - * otherwise returns nullptr. Possible failure causes: 1. size <= 0. 2. create OH_AVMemory failed. - * 3.failed to new OH_AVMemory. + * otherwise returns NULL. Possible failure causes: + * 1. size <= 0; + * 2. create OH_AVMemory failed; + * 3. failed to new OH_AVMemory. * @deprecated since 11 * @useinstead OH_AVBuffer_Create * @since 10 @@ -69,7 +71,7 @@ OH_AVMemory *OH_AVMemory_Create(int32_t size); * @brief Get the memory's virtual address * @syscap SystemCapability.Multimedia.Media.Core * @param mem Encapsulate OH_AVMemory structure instance pointer - * @return the memory's virtual address if the memory is valid, otherwise nullptr. + * @return the memory's virtual address if the memory is valid, otherwise NULL. * Possible failure causes: 1. input mem is nullptr. 2. mem's magic error. 3. mem's memory is nullptr. * @deprecated since 11 * @useinstead OH_AVBuffer_GetAddr -- Gitee From dd330068ab57182b70c069e8e29eb7bbb3925144 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=AD=90=E5=BE=AE?= Date: Thu, 14 Nov 2024 14:45:07 +0800 Subject: [PATCH 2/6] [interface_sdk] fix comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王子微 --- .../av_codec/native_avcodec_videoencoder.h | 51 ++++++++++--------- multimedia/media_foundation/native_avbuffer.h | 6 ++- multimedia/media_foundation/native_avformat.h | 2 +- 3 files changed, 32 insertions(+), 27 deletions(-) diff --git a/multimedia/av_codec/native_avcodec_videoencoder.h b/multimedia/av_codec/native_avcodec_videoencoder.h index 26028bea0..5895de538 100644 --- a/multimedia/av_codec/native_avcodec_videoencoder.h +++ b/multimedia/av_codec/native_avcodec_videoencoder.h @@ -46,8 +46,8 @@ extern "C" { #endif /** - * @brief Configure frame parameters. This interface can be used to set the encode parameters of the frame corresponding to the index, - * take effect only in Surface mode. + * @brief Configure frame parameters. This interface can be used to set the encode parameters + * of the frame corresponding to the index, take effect only in Surface mode. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec OH_AVCodec instance * @param index The index corresponding to the encode frame @@ -59,7 +59,7 @@ typedef void (*OH_VideoEncoder_OnNeedInputParameter)(OH_AVCodec *codec, uint32_t void *userData); /** - * @brief Creates a video encoder instance from the mime type, recommended for use. + * @brief Creates a video encoder instance from the mime type, it is recommended to use. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} * @return Returns a Pointer to an OH_AVCodec instance. @@ -86,7 +86,7 @@ OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, inner resource has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. @@ -103,7 +103,7 @@ OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, inner resource has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. @@ -123,7 +123,7 @@ OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallb * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, inner resource has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. @@ -133,9 +133,9 @@ OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallb OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); /** - * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated by the - * video encoder. In encode Surface mode, this interface is used to set frame-specific parameters. If this interface is used, - * it must be invoked before {@link OH_VideoEncoder_Configure}. + * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated + * by the video encoder. In encode Surface mode, this interface is used to set frame-specific parameters. + * If this interface is used, it must be invoked before {@link OH_VideoEncoder_Configure}. * * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance @@ -143,7 +143,7 @@ OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallb * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, inner resource has already released. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. @@ -155,8 +155,9 @@ OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback(OH_AVCodec *codec, void *userData); /** - * @brief To configure the encode parameters of video encoder, typically, you need to configure the description information of the - * encoded video track, such as the width, height, and pixel format. This interface must be called before Prepare is called. + * @brief To configure the encode parameters of video encoder, typically, you need to configure + * the description information of the encoded video track, such as the width, height, and pixel format. + * This interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param format A pointer to an OH_AVFormat that gives the description of the video track to be encoded @@ -261,8 +262,8 @@ OH_AVErrCode OH_VideoEncoder_Reset(OH_AVCodec *codec); OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); /** - * @brief Set encoder parameters when encoder running. Note: This interface can only be called after the encoder is started. - * At the same time, incorrect parameter settings may cause the encoding to fail. + * @brief Set encoder parameters when encoder running. Note: This interface can only be called after + * the encoder is started. At the same time, incorrect parameter settings may cause the encoding to fail. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param format OH_AVFormat handle pointer @@ -278,7 +279,7 @@ OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); /** - * @brief Get the input Surface from the video encoder, this interface must be called before Prepare is called. + * @brief Get the input surface from the video encoder, this interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param window A pointer to a OHNativeWindow instance, see {@link OHNativeWindow}, the application is responsible for @@ -293,10 +294,10 @@ OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **window); /** - * @brief Return the processed output Buffer to the encoder. + * @brief Return the processed output buffer to the encoder. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index The index value corresponding to the output Buffer, should be given by {@link OH_AVCodecOnNewOutputData} + * @param index The index value corresponding to the output buffer, should be given by {@link OH_AVCodecOnNewOutputData} * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. @@ -330,8 +331,8 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); * @brief Submit the input buffer filled with data to the video encoder. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index Enter the index value corresponding to the Buffer, should be given by {@link OH_AVCodecOnNeedInputData}. - * @param attr Information describing the data contained in the Buffer + * @param index Enter the index value corresponding to the buffer, should be given by {@link OH_AVCodecOnNeedInputData}. + * @param attr Information describing the data contained in the buffer * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. @@ -349,7 +350,8 @@ OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH * @brief In Buffer mode, the OH_AVBuffer corresponding to the index is submited to the encoder for encoding. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index Enter the index value corresponding to the Buffer, should be given by {@link OH_AVCodecOnNeedInputBuffer}. + * @param index Enter the index value corresponding to the buffer, + * should be given by {@link OH_AVCodecOnNeedInputBuffer}. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. @@ -363,7 +365,8 @@ OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH OH_AVErrCode OH_VideoEncoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); /** - * @brief In Surface mode, the encode parameters of the frame corresponding to the index is submited to the encoder for encoding. + * @brief In Surface mode, the encode parameters of the frame corresponding to the + * index is submited to the encoder for encoding. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param index Enter the index value corresponding to the input parameter, @@ -390,11 +393,11 @@ OH_AVErrCode OH_VideoEncoder_PushInputParameter(OH_AVCodec *codec, uint32_t inde * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, - * 1. the encoder is nullptr or invalid; + * {@link AV_ERR_INVALID_VAL} + * 1. the encoder is nullptr or invalid; * 2. invalid param in format; * 3. the index is vaild or consecutively assigned to the same index, - * the error do not affect the subsequent encode process. + * the error do not affect the subsequent encode process * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. diff --git a/multimedia/media_foundation/native_avbuffer.h b/multimedia/media_foundation/native_avbuffer.h index fe2b655ec..b8304710a 100644 --- a/multimedia/media_foundation/native_avbuffer.h +++ b/multimedia/media_foundation/native_avbuffer.h @@ -108,7 +108,7 @@ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr * {@link OH_AVCodecBufferAttr} * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} + * {@link AV_ERR_INVALID_VAL} * 1. input buffer or attr is nullptr; * 2. buffer's magic error; * 3. the size or offset of input buffer's memory is invalid. @@ -138,7 +138,9 @@ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); * @param format Encapsulate OH_AVFormat structure instance pointer * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} 1.input buffer or format is nullptr; 2.buffer's magic error; + * {@link AV_ERR_INVALID_VAL} + * 1.input buffer or format is nullptr; + * 2.buffer's magic error; * 3.input meta is nullptr. * @since 11 */ diff --git a/multimedia/media_foundation/native_avformat.h b/multimedia/media_foundation/native_avformat.h index b7f360190..fbfc85c2e 100644 --- a/multimedia/media_foundation/native_avformat.h +++ b/multimedia/media_foundation/native_avformat.h @@ -366,7 +366,7 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); /** - * @brief Return a string consisting of key and values contained in OH_AVFormat. + * @brief Return a string consisting of key and values contained in OH_AVFormat. * the max string that can be returned is 1024 bytes, * and the string pointer is released when the format is destroyed. * @syscap SystemCapability.Multimedia.Media.Core -- Gitee From 4db0b864a520ccb67688d296a7e646753da45a5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=AD=90=E5=BE=AE?= Date: Fri, 15 Nov 2024 11:46:29 +0800 Subject: [PATCH 3/6] [sdkc1] fix comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王子微 --- .../av_codec/native_avcodec_videoencoder.h | 54 ++++++++++--------- multimedia/media_foundation/native_avbuffer.h | 24 +++++---- multimedia/media_foundation/native_avformat.h | 31 ++++++----- multimedia/media_foundation/native_avmemory.h | 5 +- 4 files changed, 58 insertions(+), 56 deletions(-) diff --git a/multimedia/av_codec/native_avcodec_videoencoder.h b/multimedia/av_codec/native_avcodec_videoencoder.h index 5895de538..e96432a3b 100644 --- a/multimedia/av_codec/native_avcodec_videoencoder.h +++ b/multimedia/av_codec/native_avcodec_videoencoder.h @@ -87,7 +87,7 @@ OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 @@ -104,7 +104,7 @@ OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -124,7 +124,7 @@ OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallb * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -144,7 +144,7 @@ OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallb * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -164,7 +164,9 @@ OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback(OH_AVCodec *codec, * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, 1. the encoder is nullptr or invalid; 2. invalid param in format. + * {@link AV_ERR_INVALID_VAL} + * 1. the input codec pointer is non encoder instance or nullptr; + * 2. unsupported input format parameters. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -179,7 +181,7 @@ OH_AVErrCode OH_VideoEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 */ @@ -193,7 +195,7 @@ OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -203,13 +205,13 @@ OH_AVErrCode OH_VideoEncoder_Start(OH_AVCodec *codec); /** * @brief Stop the encoder and release the input and output buffer. After stopping, - * you can re-enter the Executing state through Start. + * you can re-enter the Running state through Start. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -226,7 +228,7 @@ OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -235,14 +237,14 @@ OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); OH_AVErrCode OH_VideoEncoder_Flush(OH_AVCodec *codec); /** - * @brief Reset the encoder. The encoder returns to the Initialized state. To continue coding, + * @brief Reset the encoder. The encoder returns to the Initialized state. To continue encoding, * you need to call the Configure interface again to configure the encoder instance. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 @@ -270,7 +272,9 @@ OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, 1. the encoder is nullptr or invalid; 2. invalid param in format. + * {@link AV_ERR_INVALID_VAL} + * 1. the input codec pointer is non encoder instance or nullptr; + * 2. unsupported input format parameters. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -286,7 +290,7 @@ OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format * managing the life cycle of the window, call OH_NativeWindow_DestroyNativeWindow() when done. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 @@ -301,7 +305,7 @@ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **wind * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -312,14 +316,14 @@ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **wind OH_AVErrCode OH_VideoEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); /** - * @brief Notifies the video encoder that the input stream has ended. this interface is only used in Surface mode. - * in Buffer mode, the OH_AVBuffer carries the EOS information to notify the end of the stream. + * @brief Notifies the video encoder that the input stream has ended. This interface is only used in Surface mode. + * In Buffer mode, the OH_AVBuffer carries the EOS information to notify the end of the stream. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -336,7 +340,7 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -355,7 +359,7 @@ OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -374,7 +378,7 @@ OH_AVErrCode OH_VideoEncoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -385,7 +389,7 @@ OH_AVErrCode OH_VideoEncoder_PushInputParameter(OH_AVCodec *codec, uint32_t inde /** * @brief Return the OH_AVBuffer corresponding to the processed index to the encoder. * Need to call this interface to release output buffer immediately after using. - * otherwise, the encode process will be blocked. + * Otherwise, the encode process will be blocked. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param index The index value corresponding to the output buffer, @@ -394,8 +398,8 @@ OH_AVErrCode OH_VideoEncoder_PushInputParameter(OH_AVCodec *codec, uint32_t inde * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. * {@link AV_ERR_INVALID_VAL} - * 1. the encoder is nullptr or invalid; - * 2. invalid param in format; + * 1. the input codec pointer is non encoder instance or nullptr; + * 2. unsupported input format parameters; * 3. the index is vaild or consecutively assigned to the same index, * the error do not affect the subsequent encode process * {@link AV_ERR_UNKNOWN}, unknown error. @@ -426,7 +430,7 @@ OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); * false if the codec instance is invalid. It is recommend that the invoker initialize isValid to false. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. * @since 10 */ OH_AVErrCode OH_VideoEncoder_IsValid(OH_AVCodec *codec, bool *isValid); diff --git a/multimedia/media_foundation/native_avbuffer.h b/multimedia/media_foundation/native_avbuffer.h index b8304710a..6d433ed1c 100644 --- a/multimedia/media_foundation/native_avbuffer.h +++ b/multimedia/media_foundation/native_avbuffer.h @@ -81,7 +81,7 @@ OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr or buffer's magic error. + * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr or structure verification failed of the buffer. * {@link AV_ERR_OPERATE_NOT_PERMIT} if input buffer is not user created. * @since 11 */ @@ -95,7 +95,9 @@ OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); * {@link OH_AVCodecBufferAttr} * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} 1. input buffer or attr is nullptr; 2. buffer's magic error. + * {@link AV_ERR_INVALID_VAL} + * 1. input buffer or attr is nullptr; + * 2. structure verification failed of the buffer. * @since 11 */ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr); @@ -110,7 +112,7 @@ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr * {@link AV_ERR_OK} if the execution is successful. * {@link AV_ERR_INVALID_VAL} * 1. input buffer or attr is nullptr; - * 2. buffer's magic error; + * 2. structure verification failed of the buffer; * 3. the size or offset of input buffer's memory is invalid. * @since 11 */ @@ -118,14 +120,14 @@ OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBuff /** * @brief Get parameters except basic attributes, the information is carried in OH_AVFormat. - * It should be noted that the life cycle of the OH_AVFormat instance pointed to + * It should be noted that the OH_AVFormat instance pointed to * by the return value * needs to be released by {@link OH_AVFormat_Destroy}. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Returns Encapsulate OH_AVFormat structure instance pointer if the execution is successful, * otherwise returns nullptr. Possible failure causes: * 1. input buffer is nullptr; - * 2. buffer's magic error; + * 2. structure verification failed of the buffer; * 3. buffer's meta is nullptr. * @since 11 */ @@ -139,9 +141,9 @@ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. * {@link AV_ERR_INVALID_VAL} - * 1.input buffer or format is nullptr; - * 2.buffer's magic error; - * 3.input meta is nullptr. + * 1. input buffer or format is nullptr; + * 2. structure verification failed of the buffer; + * 3. input meta is nullptr. * @since 11 */ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); @@ -153,7 +155,7 @@ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *fo * @return the buffer's virtual address if the buffer is valid, otherwise NULL * Possible failure causes: * 1. input buffer is nullptr; - * 2. structure verification error the OH_AVBuffer; + * 2. structure verification failed of the OH_AVBuffer; * 3. internal error has occurred. * @since 11 */ @@ -166,7 +168,7 @@ uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); * @return The buffer's capacity if the buffer is valid, otherwise -1 * Possible failure causes: * 1. input buffer is nullptr; - * 2. structure verification error the OH_AVBuffer; + * 2. structure verification failed of the OH_AVBuffer; * 3. internal error has occurred. * @since 11 */ @@ -180,7 +182,7 @@ int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns NULL * Possible failure causes: * 1. input buffer is nullptr; - * 2. structure verification error the OH_AVBuffer; + * 2. structure verification failed of the OH_AVBuffer; * 3. internal error has occurred. * @since 11 */ diff --git a/multimedia/media_foundation/native_avformat.h b/multimedia/media_foundation/native_avformat.h index fbfc85c2e..1c5cb843e 100644 --- a/multimedia/media_foundation/native_avformat.h +++ b/multimedia/media_foundation/native_avformat.h @@ -122,8 +122,7 @@ struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, int32_t height); /** - * @brief Destroy the specified OH_AVFormat handle resource. - * Can not be destoryed repeatedly. + * @brief Destroy the OH_AVFormat instance, can not be destoryed repeatedly. * @syscap SystemCapability.Multimedia.Media.Core * @param format pointer to an OH_AVFormat instance * @return void @@ -140,7 +139,7 @@ void OH_AVFormat_Destroy(struct OH_AVFormat *format); * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input parameter is nullptr; - * 2. structure verification error of the input OH_AVFormat. + * 2. structure verification failed of the input OH_AVFormat. * @since 9 * @version 1.0 */ @@ -155,7 +154,7 @@ bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. value type corresponding to the key is incorrect. * @since 9 @@ -172,7 +171,7 @@ bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_ * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. value type corresponding to the key is incorrect. * @since 9 @@ -189,7 +188,7 @@ bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64 * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. value type corresponding to the key is incorrect. * @since 9 @@ -206,7 +205,7 @@ bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, floa * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. value type corresponding to the key is incorrect. * @since 9 @@ -223,7 +222,7 @@ bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, dou * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input value is nullptr; * 5. value type corresponding to the key is incorrect; @@ -242,10 +241,10 @@ bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, con * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input addr is nullptr; - * 5. size is 0 or exceeds the limit by 1MB; + * 5. size is 0 or exceeds the upper limit, which is 1MB; * 6. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 @@ -261,7 +260,7 @@ bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const ui * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; * 5. The obtained key does not exist or is not set. @@ -279,7 +278,7 @@ bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_ * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; * 5. The obtained key does not exist or is not set. @@ -297,7 +296,7 @@ bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64 * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; * 5. The obtained key does not exist or is not set. @@ -315,7 +314,7 @@ bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, floa * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; * 5. The obtained key does not exist or is not set. @@ -334,7 +333,7 @@ bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, dou * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; * 5. malloc out string nullptr; @@ -355,7 +354,7 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: * 1. input format is nullptr; - * 2. structure verification error of the input format; + * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input addr is nullptr; * 5. input size is nullptr; diff --git a/multimedia/media_foundation/native_avmemory.h b/multimedia/media_foundation/native_avmemory.h index 82bfe7981..60155ce67 100644 --- a/multimedia/media_foundation/native_avmemory.h +++ b/multimedia/media_foundation/native_avmemory.h @@ -57,10 +57,7 @@ typedef struct OH_AVMemory OH_AVMemory; * @syscap SystemCapability.Multimedia.Media.Core * @param size the memory's size, bytes. * @return Returns a pointer to an OH_AVMemory instance for success, needs to be freed by OH_AVMemory_Destroy, - * otherwise returns NULL. Possible failure causes: - * 1. size <= 0; - * 2. create OH_AVMemory failed; - * 3. failed to new OH_AVMemory. + * otherwise returns NULL. * @deprecated since 11 * @useinstead OH_AVBuffer_Create * @since 10 -- Gitee From 90eda71300c771ee625b2d064d4580419949594f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=AD=90=E5=BE=AE?= Date: Tue, 19 Nov 2024 14:20:38 +0800 Subject: [PATCH 4/6] [sdkc1] fix comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王子微 --- .../av_codec/native_avcodec_videoencoder.h | 22 ++++++++++--------- multimedia/media_foundation/native_avbuffer.h | 6 ++--- multimedia/media_foundation/native_avformat.h | 14 ++++++------ 3 files changed, 22 insertions(+), 20 deletions(-) diff --git a/multimedia/av_codec/native_avcodec_videoencoder.h b/multimedia/av_codec/native_avcodec_videoencoder.h index e96432a3b..74ec2a772 100644 --- a/multimedia/av_codec/native_avcodec_videoencoder.h +++ b/multimedia/av_codec/native_avcodec_videoencoder.h @@ -69,8 +69,8 @@ typedef void (*OH_VideoEncoder_OnNeedInputParameter)(OH_AVCodec *codec, uint32_t OH_AVCodec *OH_VideoEncoder_CreateByMime(const char *mime); /** - * @brief Create a video encoder instance through the video encoder name. The premise of using this interface is to - * know the exact name of the encoder. The encoder name can be obtained through capability query. + * @brief Create a video encoder instance through the video encoder name. The premise of using this interface is + * to know the exact name of the encoder. The encoder name can be obtained through capability query. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param name Video encoder name * @return Returns a Pointer to an OH_AVCodec instance. @@ -95,8 +95,8 @@ OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); /** - * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated by the - * video encoder. This interface must be called before Prepare is called. + * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events + * generated by the video encoder. This interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} @@ -115,8 +115,8 @@ OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); /** - * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events generated by the - * video encoder. This interface must be called before Prepare is called. + * @brief Set the OH_AVCodecCallback callback function so that the application can respond to the events + * generated by the video encoder. This interface must be called before Prepare is called. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} @@ -221,8 +221,8 @@ OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); /** * @brief Clear the input and output data buffered and parameters in the encoder, for example, PPS/SPS in H264 format. - * After this interface is called, all the buffer indexes previously reported through the asynchronous callback will be - * invalidated, make sure not to access the buffers corresponding to these indexes. + * After this interface is called, all the buffer indexes previously reported through the asynchronous callback + * will be invalidated, make sure not to access the buffers corresponding to these indexes. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, @@ -301,7 +301,8 @@ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **wind * @brief Return the processed output buffer to the encoder. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index The index value corresponding to the output buffer, should be given by {@link OH_AVCodecOnNewOutputData} + * @param index The index value corresponding to the output buffer, + * should be given by {@link OH_AVCodecOnNewOutputData} * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. @@ -335,7 +336,8 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); * @brief Submit the input buffer filled with data to the video encoder. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance - * @param index Enter the index value corresponding to the buffer, should be given by {@link OH_AVCodecOnNeedInputData}. + * @param index Enter the index value corresponding to the buffer, + * should be given by {@link OH_AVCodecOnNeedInputData}. * @param attr Information describing the data contained in the buffer * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. diff --git a/multimedia/media_foundation/native_avbuffer.h b/multimedia/media_foundation/native_avbuffer.h index 6d433ed1c..97c9c479d 100644 --- a/multimedia/media_foundation/native_avbuffer.h +++ b/multimedia/media_foundation/native_avbuffer.h @@ -62,8 +62,8 @@ typedef struct OH_AVBuffer OH_AVBuffer; typedef struct OH_NativeBuffer OH_NativeBuffer; /** - * @brief Create an OH_AVBuffer instance, It should be noted that the life cycle of the OH_AVBuffer instance pointed - * to by the return value * needs to be manually released by {@link OH_AVBuffer_Destroy}. + * @brief Create an OH_AVBuffer instance, It should be noted that the OH_AVBuffer instance pointed + * to by the return value * needs to be released by {@link OH_AVBuffer_Destroy}. * @syscap SystemCapability.Multimedia.Media.Core * @param capacity the buffer's capacity, bytes * @return Returns a pointer to an OH_AVBuffer instance if the execution is successful, otherwise returns NULL. @@ -175,7 +175,7 @@ uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); /** - * @brief Get the OH_NativeBuffer instance pointer. It should be noted that the life cycle of the OH_AVBuffer + * @brief Get the OH_NativeBuffer instance pointer. It should be noted that the OH_AVBuffer * instance pointed to by the return value * needs to be released by {@link OH_NativeBuffer_Unreference}. * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer diff --git a/multimedia/media_foundation/native_avformat.h b/multimedia/media_foundation/native_avformat.h index 1c5cb843e..90c5796a6 100644 --- a/multimedia/media_foundation/native_avformat.h +++ b/multimedia/media_foundation/native_avformat.h @@ -263,7 +263,7 @@ bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const ui * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; - * 5. The obtained key does not exist or is not set. + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -281,7 +281,7 @@ bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_ * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; - * 5. The obtained key does not exist or is not set. + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -299,7 +299,7 @@ bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64 * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; - * 5. The obtained key does not exist or is not set. + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -317,7 +317,7 @@ bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, floa * 2. structure verification failed of the input format; * 3. input key is nullptr; * 4. input out is nullptr; - * 5. The obtained key does not exist or is not set. + * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -337,7 +337,7 @@ bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, dou * 3. input key is nullptr; * 4. input out is nullptr; * 5. malloc out string nullptr; - * 6. The obtained key does not exist or is not set. + * 6. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -358,7 +358,7 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con * 3. input key is nullptr; * 4. input addr is nullptr; * 5. input size is nullptr; - * 6. The obtained key does not exist or is not set. + * 6. the obtained key does not exist or is not set. * @since 9 * @version 1.0 */ @@ -369,7 +369,7 @@ bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t * the max string that can be returned is 1024 bytes, * and the string pointer is released when the format is destroyed. * @syscap SystemCapability.Multimedia.Media.Core - * @param format pointer to an OH_AVFormat instance + * @param format Pointer to an OH_AVFormat instance * @return Returns a string consisting of key and data for success, NULL for failure * Possible failure causes: 1. input format is nullptr; 2. system resources are insufficient. * @since 9 -- Gitee From e345cfcecab168cb01bd5006da859b71092660b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=AD=90=E5=BE=AE?= Date: Thu, 5 Dec 2024 14:15:07 +0800 Subject: [PATCH 5/6] [localSDKc1] change nullptr to NULL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王子微 --- .../av_codec/native_avcodec_videoencoder.h | 74 ++++++++--------- multimedia/media_foundation/native_avbuffer.h | 22 ++--- multimedia/media_foundation/native_avformat.h | 80 +++++++++---------- multimedia/media_foundation/native_avmemory.h | 6 +- 4 files changed, 91 insertions(+), 91 deletions(-) diff --git a/multimedia/av_codec/native_avcodec_videoencoder.h b/multimedia/av_codec/native_avcodec_videoencoder.h index 74ec2a772..fde236f2a 100644 --- a/multimedia/av_codec/native_avcodec_videoencoder.h +++ b/multimedia/av_codec/native_avcodec_videoencoder.h @@ -86,8 +86,8 @@ OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 @@ -103,8 +103,8 @@ OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -123,8 +123,8 @@ OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallb * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -143,8 +143,8 @@ OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallb * @param userData The data that the user rely on to execute the callback * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. @@ -163,9 +163,9 @@ OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback(OH_AVCodec *codec, * @param format A pointer to an OH_AVFormat that gives the description of the video track to be encoded * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. * {@link AV_ERR_INVALID_VAL} - * 1. the input codec pointer is non encoder instance or nullptr; + * 1. the input codec pointer is non encoder instance or NULL; * 2. unsupported input format parameters. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. @@ -181,7 +181,7 @@ OH_AVErrCode OH_VideoEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 */ @@ -194,8 +194,8 @@ OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -210,8 +210,8 @@ OH_AVErrCode OH_VideoEncoder_Start(OH_AVCodec *codec); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -227,8 +227,8 @@ OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -243,8 +243,8 @@ OH_AVErrCode OH_VideoEncoder_Flush(OH_AVCodec *codec); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 @@ -258,7 +258,7 @@ OH_AVErrCode OH_VideoEncoder_Reset(OH_AVCodec *codec); * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns a pointer to an OH_AVFormat instance. - * Return nullptr if the codec is nullptr or invaild. + * Return NULL if the codec is NULL or invaild. * @since 9 */ OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); @@ -271,9 +271,9 @@ OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); * @param format OH_AVFormat handle pointer * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. * {@link AV_ERR_INVALID_VAL} - * 1. the input codec pointer is non encoder instance or nullptr; + * 1. the input codec pointer is non encoder instance or NULL; * 2. unsupported input format parameters. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. @@ -290,7 +290,7 @@ OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format * managing the life cycle of the window, call OH_NativeWindow_DestroyNativeWindow() when done. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * @since 9 @@ -305,8 +305,8 @@ OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **wind * should be given by {@link OH_AVCodecOnNewOutputData} * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -323,8 +323,8 @@ OH_AVErrCode OH_VideoEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -341,8 +341,8 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); * @param attr Information describing the data contained in the buffer * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -360,8 +360,8 @@ OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH * should be given by {@link OH_AVCodecOnNeedInputBuffer}. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -379,8 +379,8 @@ OH_AVErrCode OH_VideoEncoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); * should be given by {@link OH_VideoEncoder_OnNeedInputParameter} * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -398,9 +398,9 @@ OH_AVErrCode OH_VideoEncoder_PushInputParameter(OH_AVCodec *codec, uint32_t inde * should be given by {@link OH_AVCodecOnNewOutputBuffer}. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal nullptr. + * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. * {@link AV_ERR_INVALID_VAL} - * 1. the input codec pointer is non encoder instance or nullptr; + * 1. the input codec pointer is non encoder instance or NULL; * 2. unsupported input format parameters; * 3. the index is vaild or consecutively assigned to the same index, * the error do not affect the subsequent encode process @@ -418,7 +418,7 @@ OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index) * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns a pointer to an OH_AVFormat instance. - * Return NULL if the encoder is nullptr or invaild. + * Return NULL if the encoder is NULL or invaild. * @since 10 */ OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); @@ -432,7 +432,7 @@ OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); * false if the codec instance is invalid. It is recommend that the invoker initialize isValid to false. * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or nullptr. + * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. * @since 10 */ OH_AVErrCode OH_VideoEncoder_IsValid(OH_AVCodec *codec, bool *isValid); diff --git a/multimedia/media_foundation/native_avbuffer.h b/multimedia/media_foundation/native_avbuffer.h index 97c9c479d..872f3b852 100644 --- a/multimedia/media_foundation/native_avbuffer.h +++ b/multimedia/media_foundation/native_avbuffer.h @@ -81,7 +81,7 @@ OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} if input buffer is nullptr or structure verification failed of the buffer. + * {@link AV_ERR_INVALID_VAL} if input buffer is NULL or structure verification failed of the buffer. * {@link AV_ERR_OPERATE_NOT_PERMIT} if input buffer is not user created. * @since 11 */ @@ -96,7 +96,7 @@ OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. * {@link AV_ERR_INVALID_VAL} - * 1. input buffer or attr is nullptr; + * 1. input buffer or attr is NULL; * 2. structure verification failed of the buffer. * @since 11 */ @@ -111,7 +111,7 @@ OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. * {@link AV_ERR_INVALID_VAL} - * 1. input buffer or attr is nullptr; + * 1. input buffer or attr is NULL; * 2. structure verification failed of the buffer; * 3. the size or offset of input buffer's memory is invalid. * @since 11 @@ -125,10 +125,10 @@ OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBuff * @syscap SystemCapability.Multimedia.Media.Core * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Returns Encapsulate OH_AVFormat structure instance pointer if the execution is successful, - * otherwise returns nullptr. Possible failure causes: - * 1. input buffer is nullptr; + * otherwise returns NULL. Possible failure causes: + * 1. input buffer is NULL; * 2. structure verification failed of the buffer; - * 3. buffer's meta is nullptr. + * 3. buffer's meta is NULL. * @since 11 */ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); @@ -141,9 +141,9 @@ OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. * {@link AV_ERR_INVALID_VAL} - * 1. input buffer or format is nullptr; + * 1. input buffer or format is NULL; * 2. structure verification failed of the buffer; - * 3. input meta is nullptr. + * 3. input meta is NULL. * @since 11 */ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); @@ -154,7 +154,7 @@ OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *fo * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return the buffer's virtual address if the buffer is valid, otherwise NULL * Possible failure causes: - * 1. input buffer is nullptr; + * 1. input buffer is NULL; * 2. structure verification failed of the OH_AVBuffer; * 3. internal error has occurred. * @since 11 @@ -167,7 +167,7 @@ uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return The buffer's capacity if the buffer is valid, otherwise -1 * Possible failure causes: - * 1. input buffer is nullptr; + * 1. input buffer is NULL; * 2. structure verification failed of the OH_AVBuffer; * 3. internal error has occurred. * @since 11 @@ -181,7 +181,7 @@ int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); * @param buffer Encapsulate OH_AVBuffer structure instance pointer * @return Returns Encapsulate OH_NativeBuffer structure instance pointer is successful, otherwise returns NULL * Possible failure causes: - * 1. input buffer is nullptr; + * 1. input buffer is NULL; * 2. structure verification failed of the OH_AVBuffer; * 3. internal error has occurred. * @since 11 diff --git a/multimedia/media_foundation/native_avformat.h b/multimedia/media_foundation/native_avformat.h index 90c5796a6..11ab1aec8 100644 --- a/multimedia/media_foundation/native_avformat.h +++ b/multimedia/media_foundation/native_avformat.h @@ -97,8 +97,8 @@ struct OH_AVFormat *OH_AVFormat_Create(void); * @param mimeType mime type * @param sampleRate sample rate * @param channelCount channel count - * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr - * Possible failure causes: 1. mimeType is nullptr; 2. new format is nullptr. + * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise NULL + * Possible failure causes: 1. mimeType is NULL; 2. new format is NULL. * @since 10 * @version 1.0 */ @@ -112,8 +112,8 @@ struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, * @param mimeType mime type * @param width width * @param height height - * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr - * Possible failure causes: 1. mimeType is nullptr; 2. new format is nullptr. + * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise NULL + * Possible failure causes: 1. mimeType is NULL; 2. new format is NULL. * @since 10 * @version 1.0 */ @@ -138,7 +138,7 @@ void OH_AVFormat_Destroy(struct OH_AVFormat *format); * @param from pointer to the OH_AVFormat handle of the copied data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input parameter is nullptr; + * 1. input parameter is NULL; * 2. structure verification failed of the input OH_AVFormat. * @since 9 * @version 1.0 @@ -153,9 +153,9 @@ bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); * @param value written data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; + * 3. input key is NULL; * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 @@ -170,9 +170,9 @@ bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_ * @param value written data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; + * 3. input key is NULL; * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 @@ -187,9 +187,9 @@ bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64 * @param value written data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; + * 3. input key is NULL; * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 @@ -204,9 +204,9 @@ bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, floa * @param value written data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; + * 3. input key is NULL; * 4. value type corresponding to the key is incorrect. * @since 9 * @version 1.0 @@ -221,10 +221,10 @@ bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, dou * @param value written data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input value is nullptr; + * 3. input key is NULL; + * 4. input value is NULL; * 5. value type corresponding to the key is incorrect; * @since 9 * @version 1.0 @@ -240,10 +240,10 @@ bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, con * @param size written data length, range is(0, 1)MB * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input addr is nullptr; + * 3. input key is NULL; + * 4. input addr is NULL; * 5. size is 0 or exceeds the upper limit, which is 1MB; * 6. value type corresponding to the key is incorrect. * @since 9 @@ -259,10 +259,10 @@ bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const ui * @param out read data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input out is nullptr; + * 3. input key is NULL; + * 4. input out is NULL; * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 @@ -277,10 +277,10 @@ bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_ * @param out read data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input out is nullptr; + * 3. input key is NULL; + * 4. input out is NULL; * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 @@ -295,10 +295,10 @@ bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64 * @param out read data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input out is nullptr; + * 3. input key is NULL; + * 4. input out is NULL; * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 @@ -313,10 +313,10 @@ bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, floa * @param out read data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input out is nullptr; + * 3. input key is NULL; + * 4. input out is NULL; * 5. the obtained key does not exist or is not set. * @since 9 * @version 1.0 @@ -332,11 +332,11 @@ bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, dou * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input out is nullptr; - * 5. malloc out string nullptr; + * 3. input key is NULL; + * 4. input out is NULL; + * 5. malloc out string NULL; * 6. the obtained key does not exist or is not set. * @since 9 * @version 1.0 @@ -353,11 +353,11 @@ bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, con * @param size Length of read data * @return The return value is TRUE for success, FALSE for failure * Possible failure causes: - * 1. input format is nullptr; + * 1. input format is NULL; * 2. structure verification failed of the input format; - * 3. input key is nullptr; - * 4. input addr is nullptr; - * 5. input size is nullptr; + * 3. input key is NULL; + * 4. input addr is NULL; + * 5. input size is NULL; * 6. the obtained key does not exist or is not set. * @since 9 * @version 1.0 @@ -371,7 +371,7 @@ bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t * @syscap SystemCapability.Multimedia.Media.Core * @param format Pointer to an OH_AVFormat instance * @return Returns a string consisting of key and data for success, NULL for failure - * Possible failure causes: 1. input format is nullptr; 2. system resources are insufficient. + * Possible failure causes: 1. input format is NULL; 2. system resources are insufficient. * @since 9 * @version 1.0 */ diff --git a/multimedia/media_foundation/native_avmemory.h b/multimedia/media_foundation/native_avmemory.h index 60155ce67..3f67c28c6 100644 --- a/multimedia/media_foundation/native_avmemory.h +++ b/multimedia/media_foundation/native_avmemory.h @@ -69,7 +69,7 @@ OH_AVMemory *OH_AVMemory_Create(int32_t size); * @syscap SystemCapability.Multimedia.Media.Core * @param mem Encapsulate OH_AVMemory structure instance pointer * @return the memory's virtual address if the memory is valid, otherwise NULL. - * Possible failure causes: 1. input mem is nullptr. 2. mem's magic error. 3. mem's memory is nullptr. + * Possible failure causes: 1. input mem is NULL. 2. mem's magic error. 3. mem's memory is NULL. * @deprecated since 11 * @useinstead OH_AVBuffer_GetAddr * @since 9 @@ -82,7 +82,7 @@ uint8_t *OH_AVMemory_GetAddr(struct OH_AVMemory *mem); * @syscap SystemCapability.Multimedia.Media.Core * @param mem Encapsulate OH_AVMemory structure instance pointer * @return the memory's size if the memory is valid, otherwise -1. - * Possible failure causes: 1. input mem is nullptr. 2. mem's magic error. 3. mem's memory is nullptr. + * Possible failure causes: 1. input mem is NULL. 2. mem's magic error. 3. mem's memory is NULL. * @deprecated since 11 * @useinstead OH_AVBuffer_GetCapacity * @since 9 @@ -97,7 +97,7 @@ int32_t OH_AVMemory_GetSize(struct OH_AVMemory *mem); * @param mem Encapsulate OH_AVMemory structure instance pointer * @return Function result code. * {@link AV_ERR_OK} if the execution is successful. - * {@link AV_ERR_INVALID_VAL} if input mem is nullptr, mem's magic error or input mem is not user created. + * {@link AV_ERR_INVALID_VAL} if input mem is NULL, mem's magic error or input mem is not user created. * @deprecated since 11 * @useinstead OH_AVBuffer_Destroy * @since 10 -- Gitee From 501ef4259e65e4c8b462cdb113809c8cea3fe4f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=AD=90=E5=BE=AE?= Date: Wed, 22 Jan 2025 11:29:05 +0800 Subject: [PATCH 6/6] [master] fix comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王子微 --- .../av_codec/native_avcodec_videoencoder.h | 16 ++++++++++++---- multimedia/media_foundation/native_averrors.h | 4 ---- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/multimedia/av_codec/native_avcodec_videoencoder.h b/multimedia/av_codec/native_avcodec_videoencoder.h index fde236f2a..24f16ddd3 100644 --- a/multimedia/av_codec/native_avcodec_videoencoder.h +++ b/multimedia/av_codec/native_avcodec_videoencoder.h @@ -48,6 +48,9 @@ extern "C" { /** * @brief Configure frame parameters. This interface can be used to set the encode parameters * of the frame corresponding to the index, take effect only in Surface mode. + * It is nedd to call {@link OH_VideoEncoder_RegisterParametercallbacks} interface to register bedfore use. + * In Buffer mode, OH_AVBuffer can directly carry the encoding parameters of frames. + * Currently, frame level QPMin/QPMax parameters are supported, and specify LTR to set the reference frame. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec OH_AVCodec instance * @param index The index corresponding to the encode frame @@ -189,7 +192,10 @@ OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); /** * @brief Start the encoder, this interface must be called after the Prepare is successful. After being - * successfully started, the encoder will start reporting NeedInputData events. + * successfully started, the encoder will start reporting NeedInputData events. In Surface mode, OnNewOutputBuffer + * will be triggered for each completed frame encoding after a correct input is received on the surface. + * In Buffer mode, the encoder trigger an input callback immediately. Each time the caller completes an input, + * the encoder performs encoding, OnNewOutputBuffer will be triggered for each completed frame encoding. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, @@ -223,6 +229,7 @@ OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); * @brief Clear the input and output data buffered and parameters in the encoder, for example, PPS/SPS in H264 format. * After this interface is called, all the buffer indexes previously reported through the asynchronous callback * will be invalidated, make sure not to access the buffers corresponding to these indexes. + * This interface cannot be called continuously. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @return Returns AV_ERR_OK if the execution is successful, @@ -342,7 +349,9 @@ OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); * @return Returns AV_ERR_OK if the execution is successful, * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. * {@link AV_ERR_NO_MEMORY}, internal errors in the input encode instance, such as an abnormal NULL. - * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non encoder instance or NULL. + * {@link AV_ERR_INVALID_VAL} + * 1. the input codec pointer is non encoder instance or NULL; + * 2. unsupported input format parameters. * {@link AV_ERR_UNKNOWN}, unknown error. * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error. * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. @@ -424,8 +433,7 @@ OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index) OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); /** - * @brief Check whether the current codec instance is valid. It can be used fault recovery or app - * switchback from the background + * @brief Check whether the current codec instance is valid. * @syscap SystemCapability.Multimedia.Media.VideoEncoder * @param codec Pointer to an OH_AVCodec instance * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, diff --git a/multimedia/media_foundation/native_averrors.h b/multimedia/media_foundation/native_averrors.h index c1c27b7c7..80cf8d292 100644 --- a/multimedia/media_foundation/native_averrors.h +++ b/multimedia/media_foundation/native_averrors.h @@ -27,11 +27,7 @@ /** * @file native_averrors.h * -<<<<<<< HEAD * @brief Media framework error code. -======= - * @brief Media framework error description. ->>>>>>> 684c9ac8 ([interface_sdk] 修改videoencder和_core的英文头文件) * * @kit AVCodecKit * @library libnative_media_core.so -- Gitee