diff --git a/zh-cn/multimedia/media_foundation/media_types.h b/zh-cn/multimedia/media_foundation/media_types.h new file mode 100644 index 000000000..86783fc48 --- /dev/null +++ b/zh-cn/multimedia/media_foundation/media_types.h @@ -0,0 +1,70 @@ +/* + * Copyright (C) 2025 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +/** + * @file media_types.h + * + * @brief 声明了常见媒体类型的定义。 + * + * @kit AVCodecKit + * @include + * @library libnative_media_core.so + * @syscap SystemCapability.Multimedia.Media.Core + * @since 18 + */ + +#ifndef MEDIA_TYPES_H +#define MEDIA_TYPES_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief HDR类型枚举。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 18 + */ +typedef enum OH_Core_HdrType { + /** + * 此选项用于标记非HDR类型。 + */ + OH_CORE_HDR_TYPE_NONE = 0, + /** + * 此选项用于标记HDR Vivid类型。 + */ + OH_CORE_HDR_TYPE_VIVID = 1, +} OH_Core_HdrType; + +#ifdef __cplusplus +} +#endif + +#endif // MEDIA_TYPES_H +/** @} */ diff --git a/zh-cn/multimedia/media_foundation/native_audio_channel_layout.h b/zh-cn/multimedia/media_foundation/native_audio_channel_layout.h new file mode 100644 index 000000000..3948b4629 --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_audio_channel_layout.h @@ -0,0 +1,353 @@ +/* + * Copyright (C) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + + +/** + * @file native_audio_channel_layout.h + * + * @brief 在录制和播放时的扬声器布局。 + * + * @kit AVCodecKit + * @include + * @syscap SystemCapability.Multimedia.Media.Core + * @since 11 + */ + +#ifndef NATIVE_AUDIO_CHANNEL_LAYOUT_H +#define NATIVE_AUDIO_CHANNEL_LAYOUT_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 音频声道集合。\n + * + * 将每一个声道映射为int64的变量。 + * @syscap SystemCapability.Multimedia.Media.Core + * @since 11 + */ +typedef enum OH_AudioChannelSet { + /** 左前声道 */ + CH_SET_FRONT_LEFT = 1ULL << 0U, + + /** 右前声道 */ + CH_SET_FRONT_RIGHT = 1ULL << 1U, + + /** 中前声道 */ + CH_SET_FRONT_CENTER = 1ULL << 2U, + + /** 低频声道 */ + CH_SET_LOW_FREQUENCY = 1ULL << 3U, + + /** 左后声道 */ + CH_SET_BACK_LEFT = 1ULL << 4U, + + /** 右后声道 */ + CH_SET_BACK_RIGHT = 1ULL << 5U, + + /** 左前中置声道 */ + CH_SET_FRONT_LEFT_OF_CENTER = 1ULL << 6U, + + /** 右前中置声道 */ + CH_SET_FRONT_RIGHT_OF_CENTER = 1ULL << 7U, + + /** 后方中置声道 */ + CH_SET_BACK_CENTER = 1ULL << 8U, + + /** 左侧声道 */ + CH_SET_SIDE_LEFT = 1ULL << 9U, + + /** 右侧声道 */ + CH_SET_SIDE_RIGHT = 1ULL << 10U, + + /** 上方中置声道 */ + CH_SET_TOP_CENTER = 1ULL << 11U, + + /** 上方左前声道 */ + CH_SET_TOP_FRONT_LEFT = 1ULL << 12U, + + /** 上方中前声道 */ + CH_SET_TOP_FRONT_CENTER = 1ULL << 13U, + + /** 上方右前声道 */ + CH_SET_TOP_FRONT_RIGHT = 1ULL << 14U, + + /** 上方左后声道 */ + CH_SET_TOP_BACK_LEFT = 1ULL << 15U, + + /** 上方中后声道 */ + CH_SET_TOP_BACK_CENTER = 1ULL << 16U, + + /** 上方右后声道 */ + CH_SET_TOP_BACK_RIGHT = 1ULL << 17U, + + /** 立体声左声道 */ + CH_SET_STEREO_LEFT = 1ULL << 29U, + + /** 立体声右声道 */ + CH_SET_STEREO_RIGHT = 1ULL << 30U, + + /** 宽左声道 */ + CH_SET_WIDE_LEFT = 1ULL << 31U, + + /** 宽右声道 */ + CH_SET_WIDE_RIGHT = 1ULL << 32U, + + /** 左环绕声道 */ + CH_SET_SURROUND_DIRECT_LEFT = 1ULL << 33U, + + /** 右环绕声道 */ + CH_SET_SURROUND_DIRECT_RIGHT = 1ULL << 34U, + + /** 低频声道2 */ + CH_SET_LOW_FREQUENCY_2 = 1ULL << 35U, + + /** 上方左侧声道 */ + CH_SET_TOP_SIDE_LEFT = 1ULL << 36U, + + /** 上方右侧声道 */ + CH_SET_TOP_SIDE_RIGHT = 1ULL << 37U, + + /** 下方中前声道 */ + CH_SET_BOTTOM_FRONT_CENTER = 1ULL << 38U, + + /** 下方左前声道 */ + CH_SET_BOTTOM_FRONT_LEFT = 1ULL << 39U, + + /** 下方右前声道 */ + CH_SET_BOTTOM_FRONT_RIGHT = 1ULL << 40U +} OH_AudioChannelSet; + +/** + * @brief 高保真立体声混响设置。\n + * + * 用int64整数来表示高保真立体声混响属性。 + * @syscap SystemCapability.Multimedia.Media.Core + * @since 11 + */ +typedef enum OH_AmbAttributeSet { + /** 一阶高保真立体声混响 */ + AMB_ORD_1 = 1ULL << 0U, + + /** 二阶高保真立体声混响 */ + AMB_ORD_2 = 2ULL << 0U, + + /** 三阶高保真立体声混响 */ + AMB_ORD_3 = 3ULL << 0U, + + /** ACN通道排序的高保真立体声混响 */ + AMB_COM_ACN = 0ULL << 8U, + + /** FUMA通道排序的高保真立体声混响 */ + AMB_COM_FUMA = 1ULL << 8U, + + /** N3D归一化的高保真立体声混响 */ + AMB_NOR_N3D = 0ULL << 12U, + + /** SN3D归一化的高保真立体声混响 */ + AMB_NOR_SN3D = 1ULL << 12U, + + /** 高保真立体声混响的声道布局 */ + AMB_MODE = 1ULL << 44U +} OH_AmbAttributeSet; + +/** + * @brief 音频声道布局。\n + * + * 用int64整数来表示在录制或播放时扬声器的外观和顺序。 + * @syscap SystemCapability.Multimedia.Media.Core + * @since 11 + */ +typedef enum OH_AudioChannelLayout { + /** 未知声道布局 */ + CH_LAYOUT_UNKNOWN = 0ULL, + + /** 单声道布局,共1个声道。 */ + CH_LAYOUT_MONO = CH_SET_FRONT_CENTER, + + /** 立体声布局,共2个声道。 */ + CH_LAYOUT_STEREO = CH_SET_FRONT_LEFT | CH_SET_FRONT_RIGHT, + + /** 立体声下混布局,共2个声道。 */ + CH_LAYOUT_STEREO_DOWNMIX = CH_SET_STEREO_LEFT | CH_SET_STEREO_RIGHT, + + /** 2.1布局,共3个声道。 */ + CH_LAYOUT_2POINT1 = CH_LAYOUT_STEREO | CH_SET_LOW_FREQUENCY, + + /** 3.0布局,共3个声道。 */ + CH_LAYOUT_3POINT0 = CH_LAYOUT_STEREO | CH_SET_BACK_CENTER, + + /** 环绕布局,共3个声道。 */ + CH_LAYOUT_SURROUND = CH_LAYOUT_STEREO | CH_SET_FRONT_CENTER, + + /** 3.1布局,共4个声道。 */ + CH_LAYOUT_3POINT1 = CH_LAYOUT_SURROUND | CH_SET_LOW_FREQUENCY, + + /** 4.0布局,共4个声道。 */ + CH_LAYOUT_4POINT0 = CH_LAYOUT_SURROUND | CH_SET_BACK_CENTER, + + /** QUAD_SIDE布局,共4个声道。 */ + CH_LAYOUT_QUAD_SIDE = CH_LAYOUT_STEREO | CH_SET_SIDE_LEFT | CH_SET_SIDE_RIGHT, + + /** QUAD布局,共4个声道。 */ + CH_LAYOUT_QUAD = CH_LAYOUT_STEREO | CH_SET_BACK_LEFT | CH_SET_BACK_RIGHT, + + /** 2.0.2布局,共4个声道。 */ + CH_LAYOUT_2POINT0POINT2 = CH_LAYOUT_STEREO | CH_SET_TOP_SIDE_LEFT | CH_SET_TOP_SIDE_RIGHT, + + /** ACN_N3D(根据ITU标准)的一阶FOA布局,共4个声道。 */ + CH_LAYOUT_AMB_ORDER1_ACN_N3D = AMB_MODE | AMB_ORD_1 | AMB_COM_ACN | AMB_NOR_N3D, + + /** ACN_SN3D(根据ITU标准)的一阶FOA布局,共4个声道。 */ + CH_LAYOUT_AMB_ORDER1_ACN_SN3D = AMB_MODE | AMB_ORD_1 | AMB_COM_ACN | AMB_NOR_SN3D, + + /** FUMA(根据ITU标准)的一阶FOA布局,共4个声道。 */ + CH_LAYOUT_AMB_ORDER1_FUMA = AMB_MODE | AMB_ORD_1 | AMB_COM_FUMA, + + /** 4.1布局,共5个声道。 */ + CH_LAYOUT_4POINT1 = CH_LAYOUT_4POINT0 | CH_SET_LOW_FREQUENCY, + + /** 5.0布局,共5个声道。 */ + CH_LAYOUT_5POINT0 = CH_LAYOUT_SURROUND | CH_SET_SIDE_LEFT | CH_SET_SIDE_RIGHT, + + /** 5.0-后置布局,共5个声道。 */ + CH_LAYOUT_5POINT0_BACK = CH_LAYOUT_SURROUND | CH_SET_BACK_LEFT | CH_SET_BACK_RIGHT, + + /** 2.1.2布局,共5个声道。 */ + CH_LAYOUT_2POINT1POINT2 = CH_LAYOUT_2POINT0POINT2 | CH_SET_LOW_FREQUENCY, + + /** 3.0.2布局,共5个声道。 */ + CH_LAYOUT_3POINT0POINT2 = CH_LAYOUT_2POINT0POINT2 | CH_SET_FRONT_CENTER, + + /** 5.1布局,共6个声道。 */ + CH_LAYOUT_5POINT1 = CH_LAYOUT_5POINT0 | CH_SET_LOW_FREQUENCY, + + /** 5.1-后置布局,共6个声道。 */ + CH_LAYOUT_5POINT1_BACK = CH_LAYOUT_5POINT0_BACK | CH_SET_LOW_FREQUENCY, + + /** 6.0布局,共6个声道。 */ + CH_LAYOUT_6POINT0 = CH_LAYOUT_5POINT0 | CH_SET_BACK_CENTER, + + /** 3.1.2布局,共6个声道。 */ + CH_LAYOUT_3POINT1POINT2 = CH_LAYOUT_3POINT1 | CH_SET_TOP_FRONT_LEFT | CH_SET_TOP_FRONT_RIGHT, + + /** 6.0-Front布局,共6个声道。 */ + CH_LAYOUT_6POINT0_FRONT = CH_LAYOUT_QUAD_SIDE | CH_SET_FRONT_LEFT_OF_CENTER | CH_SET_FRONT_RIGHT_OF_CENTER, + + /** HEXAGONAL布局,共6个声道。 */ + CH_LAYOUT_HEXAGONAL = CH_LAYOUT_5POINT0_BACK | CH_SET_BACK_CENTER, + + /** 6.1布局,共7个声道。 */ + CH_LAYOUT_6POINT1 = CH_LAYOUT_5POINT1 | CH_SET_BACK_CENTER, + + /** 6.1-后置布局,共7个声道。 */ + CH_LAYOUT_6POINT1_BACK = CH_LAYOUT_5POINT1_BACK | CH_SET_BACK_CENTER, + + /** 6.1-前置布局,共7个声道。 */ + CH_LAYOUT_6POINT1_FRONT = CH_LAYOUT_6POINT0_FRONT | CH_SET_LOW_FREQUENCY, + + /** 7.0布局,共7个声道。 */ + CH_LAYOUT_7POINT0 = CH_LAYOUT_5POINT0 | CH_SET_BACK_LEFT | CH_SET_BACK_RIGHT, + + /** 7.0-前置布局,共7个声道。 */ + CH_LAYOUT_7POINT0_FRONT = CH_LAYOUT_5POINT0 | CH_SET_FRONT_LEFT_OF_CENTER | CH_SET_FRONT_RIGHT_OF_CENTER, + + /** 7.1布局,共8个声道。 */ + CH_LAYOUT_7POINT1 = CH_LAYOUT_5POINT1 | CH_SET_BACK_LEFT | CH_SET_BACK_RIGHT, + + /** OCTAGONAL布局,共8个声道。 */ + CH_LAYOUT_OCTAGONAL = CH_LAYOUT_5POINT0 | CH_SET_BACK_LEFT | CH_SET_BACK_CENTER | CH_SET_BACK_RIGHT, + + /** 5.1.2布局,共8个声道。 */ + CH_LAYOUT_5POINT1POINT2 = CH_LAYOUT_5POINT1 | CH_SET_TOP_SIDE_LEFT | CH_SET_TOP_SIDE_RIGHT, + + /** 7.1-宽布局,共8个声道。 */ + CH_LAYOUT_7POINT1_WIDE = CH_LAYOUT_5POINT1 | CH_SET_FRONT_LEFT_OF_CENTER | CH_SET_FRONT_RIGHT_OF_CENTER, + + /** 7.1-后置宽布局,共8个声道。 */ + CH_LAYOUT_7POINT1_WIDE_BACK = CH_LAYOUT_5POINT1_BACK | CH_SET_FRONT_LEFT_OF_CENTER | CH_SET_FRONT_RIGHT_OF_CENTER, + + /** ACN_N3D(根据ITU标准)的二阶HOA布局,共9个声道。 */ + CH_LAYOUT_AMB_ORDER2_ACN_N3D = AMB_MODE | AMB_ORD_2 | AMB_COM_ACN | AMB_NOR_N3D, + + /** ACN_SN3D(根据ITU标准)的二阶HOA布局,共9个声道。 */ + CH_LAYOUT_AMB_ORDER2_ACN_SN3D = AMB_MODE | AMB_ORD_2 | AMB_COM_ACN | AMB_NOR_SN3D, + + /** FUMA(根据ITU标准)的二阶HOA布局,共9个声道。 */ + CH_LAYOUT_AMB_ORDER2_FUMA = AMB_MODE | AMB_ORD_2 | AMB_COM_FUMA, + + /** 5.1.4布局,共10个声道。 */ + CH_LAYOUT_5POINT1POINT4 = CH_LAYOUT_5POINT1 | CH_SET_TOP_FRONT_LEFT | CH_SET_TOP_FRONT_RIGHT | + CH_SET_TOP_BACK_LEFT | CH_SET_TOP_BACK_RIGHT, + + /** 7.1.2布局,共10个声道。 */ + CH_LAYOUT_7POINT1POINT2 = CH_LAYOUT_7POINT1 | CH_SET_TOP_SIDE_LEFT | CH_SET_TOP_SIDE_RIGHT, + + /** 7.1.4布局,共12个声道。 */ + CH_LAYOUT_7POINT1POINT4 = CH_LAYOUT_7POINT1 | CH_SET_TOP_FRONT_LEFT | CH_SET_TOP_FRONT_RIGHT | + CH_SET_TOP_BACK_LEFT | CH_SET_TOP_BACK_RIGHT, + + /** 10.2布局,共12个声道。 */ + CH_LAYOUT_10POINT2 = CH_SET_FRONT_LEFT | CH_SET_FRONT_RIGHT | CH_SET_FRONT_CENTER | CH_SET_TOP_FRONT_LEFT | + CH_SET_TOP_FRONT_RIGHT | CH_SET_BACK_LEFT | CH_SET_BACK_RIGHT | CH_SET_BACK_CENTER | + CH_SET_SIDE_LEFT | CH_SET_SIDE_RIGHT | CH_SET_WIDE_LEFT | CH_SET_WIDE_RIGHT, + + /** 9.1.4布局,共14个声道。 */ + CH_LAYOUT_9POINT1POINT4 = CH_LAYOUT_7POINT1POINT4 | CH_SET_WIDE_LEFT | CH_SET_WIDE_RIGHT, + + /** 9.1.6布局,共16个声道。 */ + CH_LAYOUT_9POINT1POINT6 = CH_LAYOUT_9POINT1POINT4 | CH_SET_TOP_SIDE_LEFT | CH_SET_TOP_SIDE_RIGHT, + + /** HEXADECAGONAL布局,共16个声道。 */ + CH_LAYOUT_HEXADECAGONAL = CH_LAYOUT_OCTAGONAL | CH_SET_WIDE_LEFT | CH_SET_WIDE_RIGHT | CH_SET_TOP_BACK_LEFT | + CH_SET_TOP_BACK_RIGHT | CH_SET_TOP_BACK_CENTER | CH_SET_TOP_FRONT_CENTER | + CH_SET_TOP_FRONT_LEFT | CH_SET_TOP_FRONT_RIGHT, + + /** ACN_N3D(根据ITU标准)的三阶HOA布局,共16个声道。 */ + CH_LAYOUT_AMB_ORDER3_ACN_N3D = AMB_MODE | AMB_ORD_3 | AMB_COM_ACN | AMB_NOR_N3D, + + /** ACN_SN3D(根据ITU标准)的三阶HOA布局,共16个声道。 */ + CH_LAYOUT_AMB_ORDER3_ACN_SN3D = AMB_MODE | AMB_ORD_3 | AMB_COM_ACN | AMB_NOR_SN3D, + + /** FUMA(根据ITU标准)的三阶HOA布局,共16个声道。 */ + CH_LAYOUT_AMB_ORDER3_FUMA = AMB_MODE | AMB_ORD_3 | AMB_COM_FUMA, + + /** 22.2布局,共24个声道。 */ + CH_LAYOUT_22POINT2 = CH_LAYOUT_7POINT1POINT4 | CH_SET_FRONT_LEFT_OF_CENTER | CH_SET_FRONT_RIGHT_OF_CENTER | + CH_SET_BACK_CENTER | CH_SET_TOP_CENTER | CH_SET_TOP_FRONT_CENTER | CH_SET_TOP_BACK_CENTER | + CH_SET_TOP_SIDE_LEFT | CH_SET_TOP_SIDE_RIGHT | CH_SET_BOTTOM_FRONT_LEFT | + CH_SET_BOTTOM_FRONT_RIGHT | CH_SET_BOTTOM_FRONT_CENTER | CH_SET_LOW_FREQUENCY_2 +} OH_AudioChannelLayout; + +#ifdef __cplusplus +} +#endif + +#endif // NATIVE_AUDIO_CHANNEL_LAYOUT_H + +/** @} */ \ No newline at end of file diff --git a/zh-cn/multimedia/media_foundation/native_audio_vivid.h b/zh-cn/multimedia/media_foundation/native_audio_vivid.h new file mode 100644 index 000000000..b2d607144 --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_audio_vivid.h @@ -0,0 +1,327 @@ +/* + * Copyright (C) 2026 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供的Audio Vivid元数据构建器。 + * + * @since 26.0.0 + */ + +/** + * @file native_audio_vivid.h + * + * @brief 声明Audio Vivid相关的函数和枚举。 + * + * @kit AVCodecKit + * @library libnative_media_core.so + * @include + * @syscap SystemCapability.Multimedia.Media.Core + * @since 26.0.0 + */ + +#ifndef NATIVE_AUDIO_VIVID_H +#define NATIVE_AUDIO_VIVID_H + +#include "native_avformat.h" +#include "native_averrors.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Audio Vivid编码器信号格式枚举。 + * + * @since 26.0.0 + */ +typedef enum OH_AudioVividSignalFormat { + /** + * @brief Audio Vivid信号格式为单声道,编码器接收单声道数据,内部标记声道布局为{@link OH_AudioChannelLayout}.CH_LAYOUT_MONO。 + */ + OH_AUDIO_VIVID_SIGNAL_FORMAT_MONO = 0, + /** + * @brief Audio Vivid信号格式为立体声,编码器接收双声道数据,内部标记声道布局为{@link OH_AudioChannelLayout}.CH_LAYOUT_STEREO。 + */ + OH_AUDIO_VIVID_SIGNAL_FORMAT_STEREO = 1, + /** + * @brief Audio Vivid信号格式为多声道,编码器支持声道布局{@link OH_AudioChannelLayout}.CH_LAYOUT_5POINT1、 + * {@link OH_AudioChannelLayout}.CH_LAYOUT_5POINT1POINT2、{@link OH_AudioChannelLayout}.CH_LAYOUT_5POINT1POINT4、 + * {@link OH_AudioChannelLayout}.CH_LAYOUT_7POINT1、{@link OH_AudioChannelLayout}.CH_LAYOUT_7POINT1POINT2、 + * {@link OH_AudioChannelLayout}.CH_LAYOUT_7POINT1POINT4。 + */ + OH_AUDIO_VIVID_SIGNAL_FORMAT_MC = 2, + /** + * @brief Audio Vivid信号格式为混合模式,包含声床(Bed)和对象(object)。声床的声道布局支持{@link OH_AudioChannelLayout}.CH_LAYOUT_STEREO、 + * {@link OH_AudioChannelLayout}.CH_LAYOUT_5POINT1、{@link OH_AudioChannelLayout}.CH_LAYOUT_5POINT1POINT2、 + * {@link OH_AudioChannelLayout}.CH_LAYOUT_5POINT1POINT4、{@link OH_AudioChannelLayout}.CH_LAYOUT_7POINT1、 + * {@link OH_AudioChannelLayout}.CH_LAYOUT_7POINT1POINT2、{@link OH_AudioChannelLayout}.CH_LAYOUT_7POINT1POINT4。 + */ + OH_AUDIO_VIVID_SIGNAL_FORMAT_MIX = 4, +} OH_AudioVividSignalFormat; + +/** + * @brief 表示对象声源在笛卡尔坐标系(Cartesian coordinate system)中的位置。 + * + * 笛卡尔坐标系使用x、y、z轴定义三维空间中的位置。 + * + * @since 26.0.0 + */ +typedef struct OH_CartesianPosition { + /** + * @brief 对象声源在笛卡尔坐标系中的归一化(Normalization,将数值按比例转换到指定范围内)X坐标,表示左/右维度。\n + * 取值范围为[-1.0, 1.0]。 + */ + float x; + /** + * @brief 对象声源在笛卡尔坐标系中的归一化Y坐标,表示前/后维度。\n + * 取值范围为[-1.0, 1.0]。 + */ + float y; + /** + * @brief 对象声源在笛卡尔坐标系中的归一化Z坐标,表示上/下维度。\n + * 取值范围为[-1.0, 1.0]。 + */ + float z; +} OH_CartesianPosition; + +/** + * @brief 表示极坐标系(polar coordinate system,也叫球坐标系)中的位置。 + * + * 极坐标系使用方位角、俯仰角和距离定义对象声源在三维空间中的位置。 + * @since 26.0.0 + */ +typedef struct OH_PolarPosition { + /** + * @brief 极坐标系下对象声源所在位置的方位角。\n + * 取值范围为[-180.0, 180.0],其中0.0表示正前方,90.0表示左侧,-90.0表示右侧,-180.0或180.0表示正后方。 + */ + float azimuth; + /** + * @brief 极坐标系下对象声源所在位置的俯仰角。\n + * 取值范围为[-90.0, 90.0],其中0.0表示水平,90.0表示正上方,-90.0表示正下方。 + */ + float elevation; + /** + * @brief 极坐标系下对象声源所在位置的归一化距离。\n + * 取值范围为[0.0, 1.0]。 + */ + float distance; +} OH_PolarPosition; + +/** + * @brief 表示音频对象声源在三维空间中的位置。 + * + * 该位置可以用笛卡尔坐标或极坐标表示。 + * + * @since 26.0.0 + */ +typedef struct OH_AudioObjectPosition { + /** + * @brief 对象声源是否使用笛卡尔坐标表示。\n + * true表示使用笛卡尔坐标,false表示不使用笛卡尔坐标系,使用极坐标系。 + */ + bool isCartesian; + /** + * @brief 包含笛卡尔坐标或极坐标位置数据的联合体。 + */ + union { + /** + * @brief 笛卡尔坐标表示的位置。 + */ + OH_CartesianPosition cartesian; + /** + * @brief 极坐标表示的位置。 + */ + OH_PolarPosition polar; + } pos; +} OH_AudioObjectPosition; + +/** + * @brief OH_AudioVividMetaBuilder的前向声明。 + * + * @since 26.0.0 + */ +typedef struct OH_AudioVividMetaBuilderStruct OH_AudioVividMetaBuilder; + +/** + * @brief 创建Audio Vivid元数据构建器。 + * + * @note **生命周期管理:**\n + * 通过本函数创建的实例不再使用时,必须调用{@link OH_AudioVividMetaBuilder_Destroy}手动释放,以避免内存泄漏。 + * @param builder 输出参数,用于获取OH_AudioVividMetaBuilder实例指针的指针。 + * @param format 指向包含音频格式信息的OH_AVFormat指针。 + * @return AV_ERR_OK:执行成功。\n + * AV_ERR_INVALID_VAL:参数builder或format为空指针或无效。\n + * AV_ERR_UNSUPPORT:当前设备不支持此功能。\n + * AV_ERR_UNKNOWN:创建构建器失败,属于未知错误,请查看日志获取详细信息。 + * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_Create(OH_AudioVividMetaBuilder **builder, const OH_AVFormat *format); + +/** + * @brief 更新Audio Vivid信号格式为{@link OH_AudioVividSignalFormat}.OH_AUDIO_VIVID_SIGNAL_FORMAT_MIX时的音频对象位置。 + * + * 在此信号格式下,输入编码的PCM(Pulse Code Modulation)数据中,声道排列顺序为:声床声道在前,对象声道在后。\n + * 对象声道按顺序与objectIndex对应,从0开始编号。 + * + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param objectIndex 要更新的音频对象索引,从0开始,不超过在{@link OH_AudioVividMetaBuilder_Create}创建builder时入参format + * 设置的{@link OH_MD_KEY_AUDIO_OBJECT_NUMBER}对应的值。 + * @param pos 音频对象声源的新位置。 + * @return AV_ERR_OK:执行成功。\n + * AV_ERR_INVALID_VAL:参数builder为空指针或无效,objectIndex或pos无效。 + * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_UpdateObjectPos(OH_AudioVividMetaBuilder *builder, + int32_t objectIndex, OH_AudioObjectPosition pos); + +/** + * @brief 更新Audio Vivid信号格式为{@link OH_AudioVividSignalFormat}.OH_AUDIO_VIVID_SIGNAL_FORMAT_MIX时的音频对象渲染的线性增益。 + * + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param objectIndex 要更新的音频对象索引,从0开始,不超过在{@link OH_AudioVividMetaBuilder_Create}创建builder时入参format + * 设置的{@link OH_MD_KEY_AUDIO_OBJECT_NUMBER}对应的值。 + * @param gain 对象渲染时应用的线性增益值,范围为[0.0, 6.0],线性增益0.0为静音,1.0为不变。此参数可选,如未设置则不应用增益。 + * @return AV_ERR_OK:执行成功。\n + * AV_ERR_INVALID_VAL:参数builder为空指针或无效,objectIndex或gain无效。 + * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_UpdateObjectGain(OH_AudioVividMetaBuilder *builder, + int32_t objectIndex, float gain); + +/** + * @brief 获取元数据长度。 + * + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param withStaticMeta 设置输出的长度是否包含静态元数据。true表示输出长度包含静态元数据;false表示输出长度仅包含动态元数据。 + * @param len 用于接收元数据长度的指针。单位为字节。 + * @return AV_ERR_OK:执行成功。\n + * AV_ERR_INVALID_VAL:参数builder为空指针或无效,len为空指针。 + * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_GetMetaLen(const OH_AudioVividMetaBuilder *builder, bool withStaticMeta, + int32_t *len); + +/** + * @brief 获取元数据缓冲区。 + * + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param withStaticMeta 设置输出的长度是否包含静态元数据。true表示输出缓冲区包含静态元数据;false表示输出缓冲区仅包含动态元数据。 + * @param buffer 用于接收元数据内容的缓冲区指针。 + * @param len 缓冲区长度。单位为字节。 + * @return AV_ERR_OK:执行成功。\n + * AV_ERR_INVALID_VAL:builder为空指针或无效,buffer为空指针或len不足。 + * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_GetMeta(const OH_AudioVividMetaBuilder *builder, bool withStaticMeta, + uint8_t *buffer, int32_t len); + +/** + * @brief 销毁Audio Vivid元数据构建器并释放资源。 + * + * @param builder 指向待销毁的OH_AudioVividMetaBuilder的指针。 + * @return AV_ERR_OK:执行成功。\n + * AV_ERR_INVALID_VAL:参数builder为空指针。 + * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_Destroy(OH_AudioVividMetaBuilder *builder); + +#ifdef __cplusplus +} +#endif + +/** + * @brief 创建一个空的Audio Vivid元数据构建器。 + * + * 该函数用于合并Audio Vivid元数据的场景。在创建一个空的元数据构造器后, + * 用户可以通过调用{@link OH_AudioVividMetaBuilder_UpdateBaseMeta}接口来增加、修改或者删除音频对象。 + * + * @note 生命周期管理: + * 通过本函数创建的实例不再使用时,必须调用{@link OH_AudioVividMetaBuilder_Destroy}手动释放,以避免内存泄漏。 + * @param builder 输出参数,用于获取OH_AudioVividMetaBuilder实例指针的指针。 + * @return
    + *
  • AV_ERR_OK:执行成功。
  • + *
  • AV_ERR_INVALID_VAL:参数builder为空指针或无效。
  • + *
  • AV_ERR_UNSUPPORT:当前设备不支持此功能。
  • + *
  • AV_ERR_UNKNOWN:创建构建器失败,属于未知错误,请查看日志获取详细信息。
  • + *
+ * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_CreateEmptyBuilder(OH_AudioVividMetaBuilder **builder); + +/** + * @brief 更新Audio Vivid元数据构造器的基础元数据。 + * + * buffer需要包含完整的Audio Vivid元数据。 + * 构造器会将元数据里的音频声床和音频对象信息保留下来。 + * + * @note 约束条件: + * 基础元数据内音频的声床声道数 + 对象数必须小于等于16个。 + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param buffer 指向包含基础元数据的指针。 + * @param len 缓冲区长度。单位为字节(Byte)。 + * @return
    + *
  • AV_ERR_OK:执行成功。
  • + *
  • AV_ERR_INVALID_VAL:参数builder、format为空指针或无效。
  • + *
+ * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_UpdateBaseMeta(OH_AudioVividMetaBuilder *builder, const uint8_t *buffer, + int32_t len); + +/** + * @brief Audio Vivid元数据构造器内添加一个音频对象。 + * + * 添加音频对象后,可以通过{@link OH_AudioVividMetaBuilder_UpdateObjectPos}和{@link OH_AudioVividMetaBuilder_UpdateObjectGain}接口, + * 更新该对象的位置和对象渲染的线性增益。 + * + * @note 约束条件: + * 音频的声床声道数 + 对象数必须小于等于16个。 + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param objectIndex 输出参数,用于输出新增对象的索引。 + * @return
    + *
  • AV_ERR_OK:执行成功。
  • + *
  • AV_ERR_INVALID_VAL:参数builder、objectIndex为空指针或无效。
  • + *
  • AV_ERR_UNKNOWN:添加对象失败,属于未知错误,请查看日志获取详细信息。
  • + *
+ * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_AddObject(OH_AudioVividMetaBuilder *builder, int32_t *objectIndex); + +/** + * @brief 从Audio Vivid元数据构造器内删除一个音频对象。 + * + * 只有通过{@link OH_AudioVividMetaBuilder_AddObject}函数创建的音频对象可以被删除。 + * 通过{@link OH_AudioVividMetaBuilder_Destroy}函数新增的音频对象无法删除。 + * 删除音频对象后,其他音频对象的索引保持不变。 + * + * @param builder 指向OH_AudioVividMetaBuilder的指针。 + * @param objectIndex 要移除的音频对象的索引。 + * @return
    + *
  • AV_ERR_OK:执行成功。
  • + *
  • AV_ERR_INVALID_VAL:
  • + *
  • 1. 参数builder为空指针或无效;
  • + *
  • 2. 参数objectIndex无效。
  • + *
+ * @since 26.0.0 + */ +OH_AVErrCode OH_AudioVividMetaBuilder_RemoveObject(OH_AudioVividMetaBuilder *builder, int32_t objectIndex); + +#endif // NATIVE_AUDIO_VIVID_H + +/** @} */ \ No newline at end of file diff --git a/zh-cn/multimedia/media_foundation/native_avbuffer.h b/zh-cn/multimedia/media_foundation/native_avbuffer.h new file mode 100644 index 000000000..65768dd89 --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_avbuffer.h @@ -0,0 +1,188 @@ +/* + * Copyright (C) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + + +/** + * @file native_avbuffer.h + * + * @brief 声明了媒体数据结构AVBuffer的函数接口。 + * @sample [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) + * + * @kit AVCodecKit + * @include + * @library libnative_media_core.so + * @syscap SystemCapability.Multimedia.Media.Core + * @since 11 + */ + +#ifndef NATIVE_AVBUFFER_H +#define NATIVE_AVBUFFER_H + +#include +#include +#include "native_averrors.h" +#include "native_avformat.h" +#include "native_avbuffer_info.h" + +#ifdef __cplusplus +extern "C" { +#endif +/** + * @brief 为媒体内存接口定义native层对象。 + * @since 11 + */ +typedef struct OH_AVBuffer OH_AVBuffer; +/** + * @brief 为图形内存接口定义native层对象。 + * @since 11 + */ +typedef struct OH_NativeBuffer OH_NativeBuffer; + +/** + * @brief 创建OH_AVBuffer实例。 + * 需要注意的是,返回值指向的创建OH_AVBuffer的实例需要开发者主动调用接口释放,请参阅{@link OH_AVBuffer_Destroy}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param capacity 创建内存的大小,单位字节。 + * @return 如果创建成功,则返回OH_AVBuffer实例的指针,如果失败,则返回NULL。\n + * 可能的失败原因:\n + * 1.capacity <= 0。\n + * 2.出现内部错误,系统没有资源等。 + * @since 11 + */ +OH_AVBuffer *OH_AVBuffer_Create(int32_t capacity); + +/** + * @brief 释放OH_AVBuffer实例指针的资源,同一个buffer不允许重复销毁。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @return AV_ERR_OK:操作成功。\n + * AV_ERR_INVALID_VAL:输入的buffer为空指针或者buffer格式校验失败。\n + * AV_ERR_OPERATE_NOT_PERMIT:输入的buffer不是用户创建的。 + * @since 11 + */ +OH_AVErrCode OH_AVBuffer_Destroy(OH_AVBuffer *buffer); + +/** + * @brief 获取数据缓冲区的pts、size、offset、flags高频属性参数。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @param attr 指向OH_AVCodecBufferAttr实例的指针。 + * @return AV_ERR_OK:操作成功。\n + * AV_ERR_INVALID_VAL:可能的原因:\n + * 1. 输入的buffer或attr为空指针。\n + * 2. buffer结构校验失败。 + * @since 11 + */ +OH_AVErrCode OH_AVBuffer_GetBufferAttr(OH_AVBuffer *buffer, OH_AVCodecBufferAttr *attr); + +/** + * @brief 设置数据缓冲区的pts、size、offset、flags高频属性参数。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @param attr 指向OH_AVCodecBufferAttr实例的指针。 + * @return AV_ERR_OK:操作成功。\n + * AV_ERR_INVALID_VAL:可能的原因:\n + * 1. 输入的buffer或attr为空指针。\n + * 2. buffer结构校验失败。\n + * 3. 输入buffer中内存的size或offset是无效值。 + * @since 11 + */ +OH_AVErrCode OH_AVBuffer_SetBufferAttr(OH_AVBuffer *buffer, const OH_AVCodecBufferAttr *attr); + +/** + * @brief 获取除基础属性外的其他参数,信息在OH_AVFormat中承载。 + * 需要注意的是,返回值指向的创建OH_AVFormat的实例需要开发者主动释放,请参阅{@link OH_AVFormat_Destroy}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @return AV_ERR_OK:操作成功。\n + * AV_ERR_INVALID_VAL:可能的原因:\n + * 1. 输入的buffer为空指针。\n + * 2. 输入buffer的meta为空指针。\n + * 3. buffer结构校验失败。 + * @since 11 + */ +OH_AVFormat *OH_AVBuffer_GetParameter(OH_AVBuffer *buffer); + +/** + * @brief 设置除基础属性外的其他参数,信息在OH_AVFormat中承载。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @param format 指向OH_AVFormat实例的指针。 + * @return AV_ERR_OK:操作成功。\n + * AV_ERR_INVALID_VAL:可能的原因:\n + * 1. 输入的buffer或format为空指针。\n + * 2. 输入buffer的meta为空指针。\n + * 3. buffer结构校验失败。 + * @since 11 + */ +OH_AVErrCode OH_AVBuffer_SetParameter(OH_AVBuffer *buffer, const OH_AVFormat *format); + +/** + * @brief 获取数据缓冲区的虚拟地址。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @return 如果成功,则返回数据缓冲区的虚拟地址,如果失败,则返回NULL。\n + * 可能的失败原因:\n + * 1.输入的buffer为空指针。\n + * 2.OH_AVBuffer结构校验失败。\n + * 3.出现内部错误。 + * @since 11 + */ +uint8_t *OH_AVBuffer_GetAddr(OH_AVBuffer *buffer); + +/** + * @brief 获取数据缓冲区的容量(字节数)。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @return 如果成功,则返回数据缓冲区的容量,如果失败,则返回-1。\n + * 可能的失败原因:\n + * 1.输入的buffer为空指针。\n + * 2.OH_AVBuffer结构校验失败。\n + * 3.出现内部错误。 + * @since 11 + */ +int32_t OH_AVBuffer_GetCapacity(OH_AVBuffer *buffer); + +/** + * @brief 获取OH_NativeBuffer实例的指针。 + * 需要注意的是,返回值指向的创建OH_NativeBuffer的实例需要开发者主动调用接口释放,请参阅{@link OH_NativeBuffer_Unreference}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param buffer 指向OH_AVBuffer实例的指针。 + * @return 如果成功,则返回OH_NativeBuffer实例的指针,如果失败,则返回NULL。\n + * 可能的失败原因:\n + * 1.输入的buffer为空指针。\n + * 2.OH_AVBuffer结构校验失败。\n + * 3.出现内部错误。 + * @since 11 + */ +OH_NativeBuffer *OH_AVBuffer_GetNativeBuffer(OH_AVBuffer *buffer); + +#ifdef __cplusplus +} +#endif + +#endif // NATIVE_AVBUFFER_H + +/** @} */ \ No newline at end of file diff --git a/zh-cn/multimedia/media_foundation/native_avbuffer_info.h b/zh-cn/multimedia/media_foundation/native_avbuffer_info.h new file mode 100644 index 000000000..fc243dfca --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_avbuffer_info.h @@ -0,0 +1,101 @@ +/* + * Copyright (C) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + + +/** + * @file native_avbuffer_info.h + * + * @brief 声明了媒体数据结构AVBuffer属性的定义。 + * @sample [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) + * + * @kit AVCodecKit + * @include + * @library libnative_media_core.so + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +#ifndef NATIVE_AVBUFFER_INFO_H +#define NATIVE_AVBUFFER_INFO_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif +/** + * @brief 枚举OH_AVCodec缓冲区标记的类别。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ +typedef enum OH_AVCodecBufferFlags { + /** 表示为普通帧。 */ + AVCODEC_BUFFER_FLAGS_NONE = 0, + /** 表示缓冲区是流结束帧。 */ + AVCODEC_BUFFER_FLAGS_EOS = 1 << 0, + /** 表示缓冲区包含关键帧。 */ + AVCODEC_BUFFER_FLAGS_SYNC_FRAME = 1 << 1, + /** 表示缓冲区中的数据只是帧的一部分。 */ + AVCODEC_BUFFER_FLAGS_INCOMPLETE_FRAME = 1 << 2, + /** 表示缓冲区包含编解码特定数据。 */ + AVCODEC_BUFFER_FLAGS_CODEC_DATA = 1 << 3, + /** + * @brief 表示缓冲区被解码依赖,解码之后的数据可丢弃。 + * @since 12 + */ + AVCODEC_BUFFER_FLAGS_DISCARD = 1 << 4, + /** + * @brief 表示缓冲区不被参考可直接丢弃。 + * @since 12 + */ + AVCODEC_BUFFER_FLAGS_DISPOSABLE = 1 << 5, +} OH_AVCodecBufferFlags; + +/** + * @brief 定义OH_AVCodec的缓冲区描述信息。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ +typedef struct OH_AVCodecBufferAttr { + /** 此缓冲区的显示时间戳(以微秒为单位)。 */ + int64_t pts; + /** 缓冲区中包含的数据的大小(以字节为单位)。 */ + int32_t size; + /** 此缓冲区中有效数据的起始偏移量。 */ + int32_t offset; + /** 此缓冲区具有的标志,请参阅{@link OH_AVCodecBufferFlags}。 */ + uint32_t flags; +} OH_AVCodecBufferAttr; + +#ifdef __cplusplus +} +#endif + +#endif // NATIVE_AVBUFFER_INFO_H + +/** @} */ diff --git a/zh-cn/multimedia/media_foundation/native_averrors.h b/zh-cn/multimedia/media_foundation/native_averrors.h new file mode 100644 index 000000000..6337fe45f --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_averrors.h @@ -0,0 +1,215 @@ +/* + * Copyright (C) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +/** + * @file native_averrors.h + * + * @brief 媒体框架错误码。 + * + * @kit AVCodecKit + * @include + * @library libnative_media_core.so + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +#ifndef NATIVE_AVERRORS_H +#define NATIVE_AVERRORS_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 媒体框架错误码。 + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + * @version 1.0 + */ +typedef enum OH_AVErrCode { + /** + * 操作成功。 + */ + AV_ERR_OK = 0, + /** + * 无内存。 + */ + AV_ERR_NO_MEMORY = 1, + /** + * 操作不允许。 + */ + AV_ERR_OPERATE_NOT_PERMIT = 2, + /** + * 无效值。 + */ + AV_ERR_INVALID_VAL = 3, + /** + * IO错误。 + */ + AV_ERR_IO = 4, + /** + * 超时错误。 + */ + AV_ERR_TIMEOUT = 5, + /** + * 未知错误。 + */ + AV_ERR_UNKNOWN = 6, + /** + * 服务死亡。 + */ + AV_ERR_SERVICE_DIED = 7, + /** + * 当前状态不支持此操作。 + */ + AV_ERR_INVALID_STATE = 8, + /** + * 未支持的接口。 + */ + AV_ERR_UNSUPPORT = 9, + /** + * @error 输入数据错误。 + * @since 12 + */ + AV_ERR_INPUT_DATA_ERROR = 10, + /** + * @error 不支持的格式。 + * @since 18 + */ + AV_ERR_UNSUPPORTED_FORMAT = 11, + /** + * 扩展错误码初始值。 + */ + AV_ERR_EXTEND_START = 100, + /** + * @error DRM起始错误码。 + * @since 12 + */ + AV_ERR_DRM_BASE = 200, + /** + * @error DRM解密失败。 + * @since 12 + */ + AV_ERR_DRM_DECRYPT_FAILED = 201, + /** + * @error 视频起始错误码。 + * @since 12 + */ + AV_ERR_VIDEO_BASE = 300, + /** + * @error 视频不支持色彩空间转换。 + * @since 12 + */ + AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION = 301, + /** + * @error 无法找到主机,可能服务器地址错误。 + * @since 14 + */ + AV_ERR_IO_CANNOT_FIND_HOST = 5411001, + /** + * @error 网络连接超时。 + * @since 14 + */ + AV_ERR_IO_CONNECTION_TIMEOUT = 5411002, + /** + * @error 网络异常导致连接失败。 + * @since 14 + */ + AV_ERR_IO_NETWORK_ABNORMAL = 5411003, + /** + * @error 网络不可用导致连接失败。 + * @since 14 + */ + AV_ERR_IO_NETWORK_UNAVAILABLE = 5411004, + /** + * @error 无网络访问权限。 + * @since 14 + */ + AV_ERR_IO_NO_PERMISSION = 5411005, + /** + * @error 客户端请求参数错误或超出处理能力。 + * @since 14 + */ + AV_ERR_IO_NETWORK_ACCESS_DENIED = 5411006, + /** + * @error 无法找到可用网络资源。 + * @since 14 + */ + AV_ERR_IO_RESOURCE_NOT_FOUND = 5411007, + /** + * @error 由于未携带客户端证书、证书无效或过期导致服务器验证失败。 + * @since 14 + */ + AV_ERR_IO_SSL_CLIENT_CERT_NEEDED = 5411008, + /** + * @error 由于未携带服务器证书、证书无效或过期导致客户端验证失败。 + * @since 14 + */ + AV_ERR_IO_SSL_CONNECT_FAIL = 5411009, + /** + * @error SSL服务器证书不受信任。 + * @since 14 + */ + AV_ERR_IO_SSL_SERVER_CERT_UNTRUSTED = 5411010, + /** + * @error 网络协议不支持该请求。 + * @since 14 + */ + AV_ERR_IO_UNSUPPORTED_REQUEST = 5411011, + /** + * @error 不允许HTTP明文访问。 + * @since 23 + */ + AV_ERR_IO_CLEARTEXT_NOT_PERMITTED = 5411012, + /** + * @error 同步模式下流格式发生变更。 + * 可以通过调用接口{@link OH_VideoEncoder_GetOutputDescription}(视频编码)、{@link OH_VideoDecoder_GetOutputDescription}(视频解码)、 + * {@link OH_AudioCodec_GetOutputDescription}音频编解码来获取更新后流的配置信息。 + * @since 20 + */ + AV_ERR_STREAM_CHANGED = 5410005, + /** + * @error 同步模式下临时缓冲区查询失败,建议等待短暂间隔后重试操作。 + * @since 20 + */ + AV_ERR_TRY_AGAIN_LATER = 5410006, + /** + * @error 该媒体源或者当前设备不支持超分。 + * @since 23 + */ + AV_ERR_SUPER_RESOLUTION_UNSUPPORTED = 5410003, + /** + * @error 未使能超分。 + * @since 23 + */ + AV_ERR_SUPER_RESOLUTION_NOT_ENABLED = 5410004, +} OH_AVErrCode; + +#ifdef __cplusplus +} +#endif + +#endif // NATIVE_AVERRORS_H +/** @} */ diff --git a/zh-cn/multimedia/media_foundation/native_avformat.h b/zh-cn/multimedia/media_foundation/native_avformat.h new file mode 100644 index 000000000..2142a400a --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_avformat.h @@ -0,0 +1,495 @@ +/* + * Copyright (C) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +/** + * @file native_avformat.h + * + * @brief 声明了OH_AVFormat相关的函数和枚举。 + * @sample [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) + * + * @kit AVCodecKit + * @include + * @library libnative_media_core.so + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +#ifndef NATIVE_AVFORMAT_H +#define NATIVE_AVFORMAT_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif +/** + * @brief 为OH_AVFormat接口定义native层对象。 + * @since 9 + */ +typedef struct OH_AVFormat OH_AVFormat; + +/** + * @brief 视频像素格式的枚举类。 + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + * @version 1.0 + */ +typedef enum OH_AVPixelFormat { + /** + * yuv 420 planar。 + */ + AV_PIXEL_FORMAT_YUVI420 = 1, + /** + * NV12. yuv 420 semiplanar。 + */ + AV_PIXEL_FORMAT_NV12 = 2, + /** + * NV21. yvu 420 semiplanar。 + */ + AV_PIXEL_FORMAT_NV21 = 3, + /** + * 像素格式从surface获取。只作用于Surface模式,Buffer模式不生效。 + */ + AV_PIXEL_FORMAT_SURFACE_FORMAT = 4, + /** + * RGBA8888。 + */ + AV_PIXEL_FORMAT_RGBA = 5, + /** + * @brief RGBA1010102。 + * @since 20 + */ + AV_PIXEL_FORMAT_RGBA1010102 = 6, +} OH_AVPixelFormat; + +/** + * @brief 创建OH_AVFormat实例,用于读取数据。 + * @syscap SystemCapability.Multimedia.Media.Core + * @return 返回指向OH_AVFormat实例的指针。系统资源不足时返回NULL。 + * @since 9 + * @version 1.0 + */ +struct OH_AVFormat *OH_AVFormat_Create(void); + +/** + * @brief 创建音频OH_AVFormat实例指针并预设置指定参数,用于读写数据。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param mimeType MIME类型描述字符串,请参阅{@link AVCODEC_MIMETYPE}。 + * @param sampleRate 采样率,单位Hz。 + * @param channelCount 声道个数,如1为单声道,2为双声道。 + * @return 如果创建成功,返回指向OH_AVFormat实例的指针,如果失败,则返回NULL。\n + * 可能的失败原因:\n + * 1. 传入的mimeType为NULL。\n + * 2. 系统资源不足。 + * @since 10 + * @version 1.0 + */ +struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, + int32_t sampleRate, + int32_t channelCount); + +/** + * @brief 创建视频OH_AVFormat实例指针并预设置指定参数,用于读写数据。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param mimeType MIME类型描述字符串,请参阅{@link AVCODEC_MIMETYPE}。 + * @param width 图像的宽度,单位为pixel。 + * @param height 图像的高度,单位为pixel。 + * @return 如果创建成功,返回指向OH_AVFormat实例的指针,如果失败,则返回NULL。\n + * 可能的失败原因:\n + * 1. 传入的mimeType为NULL。\n + * 2. 系统资源不足。 + * @since 10 + * @version 1.0 + */ +struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, + int32_t width, + int32_t height); + +/** + * @brief 销毁OH_AVFormat实例,不允许重复销毁。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @since 9 + * @version 1.0 + */ +void OH_AVFormat_Destroy(struct OH_AVFormat *format); + +/** + * @brief 复制OH_AVFormat实例。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param to OH_AVFormat实例,用于接收数据。 + * @param from 指向复制数据的OH_AVFormat实例的指针。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入参数为空指针。\n + * 2. 输入的OH_AVFormat参数结构校验失败。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); + +/** + * @brief 对OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)赋int类型的值。 + * 该接口仅能设置int类型的参数,参数类型定义详见{@link native_avcodec_base.h}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param value 写入数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 设置的key对应的value类型错误。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); + +/** + * @brief 对OH_AVFormat的key赋unsigned int类型的值。 + * + * 该接口仅能设置unsigned int类型的参数,具体参数类型定义请参考{@link native_avcodec_base.h}。 + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param value 写入数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。 + * @since 23 + */ +bool OH_AVFormat_SetUintValue(struct OH_AVFormat *format, const char *key, uint32_t value); + +/** + * @brief 对OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)赋long类型的值。 + * 该接口仅能设置long类型的参数,参数类型定义详见{@link native_avcodec_base.h}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param value 写入数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 设置的key对应的value类型错误。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); + +/** + * @brief 对OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)赋float类型的值。 + * 该接口仅能设置float类型的参数,参数类型定义详见{@link native_avcodec_base.h}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param value 写入数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 设置的key对应的value类型错误。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); + +/** + * @brief 对OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)赋double类型的值。 + * 该接口仅能设置double类型的参数,参数类型定义详见{@link native_avcodec_base.h}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param value 写入数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 设置的key对应的value类型错误。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); + +/** + * @brief 对OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)赋string类型的值。 + * 该接口仅能设置string类型的参数,参数类型定义详见{@link native_avcodec_base.h}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param value 写入字符串数据(使用建议:设置字符长度不超过256字节)。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入value为空指针。\n + * 5. 设置的key对应的value类型错误。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); + +/** + * @brief 将指定长度的数据块写入OH_AVFormat。 + * 该接口仅能设置buffer类型的参数,参数类型定义详见{@link native_avcodec_base.h}。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param addr 写入数据的地址,生命周期由开发者管理。 + * @param size 写入数据的长度,范围为(0, 1]MB。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入addr为空指针。\n + * 5. size为0或超过限制1MB。\n + * 6. 设置的key对应的value类型错误。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); + +/** + * @brief 从OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)获取int类型的值。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 读取数据的键。 + * @param out 读取数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入out为空指针。\n + * 5. 获取的key不存在或者未设置。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); + +/** + * @brief 使用key从OH_AVFormat中获取unsigned int类型的值。 + * @param format 指向OH_AVFormat实例的指针。 + * @param key 读取数据的键。 + * @param out 读取数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入out为空指针。 + * @since 23 + */ +bool OH_AVFormat_GetUintValue(struct OH_AVFormat *format, const char *key, uint32_t *out); + +/** + * @brief 从OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)获取long类型的值。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 读取数据的键。 + * @param out 读取数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入out为空指针。\n + * 5. 获取的key不存在或者未设置。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); + +/** + * @brief 从OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)获取float类型的值。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 读取数据的键。 + * @param out 读取数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入out为空指针。\n + * 5. 获取的key不存在或者未设置。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); + +/** + * @brief 从OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)获取double类型的值。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 读取数据的键。 + * @param out 读取数据的值。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入out为空指针。\n + * 5. 获取的key不存在或者未设置。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); + +/** + * @brief 从OH_AVFormat的[key](capi-codecbase.md#媒体数据键值对)获取string类型的值。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 读取数据的键。 + * @param out 读取string指针,out数据的生命周期与format内string对应,如果开发者需要长时间保持它,必须进行拷贝内存。out最大输出字符串长度为256字节,如果长度超过256字节,会报false。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入out为空指针。\n + * 5. malloc出的out字符串资源不足。\n + * 6. 获取的key不存在或者未设置。\n + * 7. 输出out的长度超过256字节。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, const char **out); + +/** + * @brief 从OH_AVFormat中读取指定长度的数据块。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 要读取数据的键。 + * @param addr 生命周期与format相同,与format一同销毁。如果开发者需要长时间保持它,必须进行内存拷贝。 + * @param size 读到数据的长度。 + * @return 返回值为true表示成功,为false表示失败。 + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入addr为空指针。\n + * 5. 输入size为空指针。\n + * 6. 获取的key不存在或者未设置。 + * @since 9 + * @version 1.0 + */ +bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); + +/** + * @brief 从OH_AVFormat中读取一个int32_t数据的数组。\n + * + * 需要注意的是,获取的buffer生命周期与OH_AVFormat对象绑定,当format销毁时自动失效。\n + * 如果开发者需要长时间保持绑定,应用程序必须将数据显式复制到新分配的内存。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 要读取数据的键。 + * @param addr 保存数据内存的指针。 + * @param size 读到数据的元素数量。 + * @return 返回值为true表示成功,为false表示失败。\n + * 可能的失败原因: + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入addr为空指针。\n + * 5. 输入size为空指针。 + * @since 20 + */ +bool OH_AVFormat_GetIntBuffer(struct OH_AVFormat *format, const char *key, int32_t **addr, size_t *size); + +/** + * @brief 返回OH_AVFormat中包含的key-value组成的字符串。最大可返回1024字节的字符串,销毁format时释放字符串指针。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @return 如果创建成功,返回一个由key-value组成的字符串,如果失败,则返回NULL。 + * 可能的失败原因:\n + * 1. 传入的format为NULL。\n + * 2. 系统资源不足。 + * @since 9 + * @version 1.0 + */ +const char *OH_AVFormat_DumpInfo(struct OH_AVFormat *format); + +/** + * @brief 将指定长度int32_t类型的数据块写入OH_AVFormat。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param format 指向OH_AVFormat实例的指针。 + * @param key 写入数据的键。 + * @param addr 写入数据的地址,生命周期由开发者管理。 + * @param size 写入数据的长度(以元素为单位,不是字节数)。 + * @return 返回true表示成功,返回false表示失败。\n + * 可能的失败原因:\n + * 1. 输入format为空指针。\n + * 2. 输入format参数结构校验失败。\n + * 3. 输入key为空指针。\n + * 4. 输入addr为空指针。\n + * 5. 输入size为0。 + * @since 20 + */ +bool OH_AVFormat_SetIntBuffer(struct OH_AVFormat *format, const char *key, const int32_t *addr, size_t size); + +/** + * @brief 获取OH_AVFormat中包含的键总数。 + * @param format 指向一个OH_AVFormat实例的指针。 + * @return 成功时返回键的数量;失败时返回 0。 + * @details 可能的失败原因:\n + * 1. 输入的format为空指针;\n + * 2. 系统资源不足。 + * @since 23 + */ +uint32_t OH_AVFormat_GetKeyCount(OH_AVFormat *format); + +/** + * @brief 通过索引从OH_AVFormat中获取键名字符串。 + * @param format 指向一个OH_AVFormat实例的指针。 + * @param index 要查询键的索引值,取值范围为[0, OH_AVFormat_GetKeyCount(format))。 + * @param key 用于接收键名字符串的输出指针;该字符串的生命周期与format绑定。 + * @return 成功时返回true,失败时返回false。 + * @details 可能的失败原因:\n + * 1. 输入的format为空指针;\n + * 2. index超出有效范围;\n + * 3. key为空指针;\n + * 4. 系统资源不足。 + * @since 23 + */ +bool OH_AVFormat_GetKey(OH_AVFormat *format, uint32_t index, const char **key); + +#ifdef __cplusplus +} +#endif + +#endif // NATIVE_AVFORMAT_H + +/** @} */ + diff --git a/zh-cn/multimedia/media_foundation/native_avmemory.h b/zh-cn/multimedia/media_foundation/native_avmemory.h new file mode 100644 index 000000000..5c53d40f7 --- /dev/null +++ b/zh-cn/multimedia/media_foundation/native_avmemory.h @@ -0,0 +1,123 @@ +/* + * Copyright (C) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Core + * @{ + * + * @brief Core模块提供用于媒体系统的基础骨干能力,包含内存、错误码、媒体数据结构等相关函数。 + * + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + + +/** + * @file native_avmemory.h + * + * @brief 声明了媒体数据结构AVMemory的定义。 + * + * @kit AVCodecKit + * @include + * @library libnative_media_core.so + * @syscap SystemCapability.Multimedia.Media.Core + * @since 9 + */ + +#ifndef NATIVE_AVMEMORY_H +#define NATIVE_AVMEMORY_H + +#include +#include "native_averrors.h" + +#ifdef __cplusplus +extern "C" { +#endif +/** + * @brief 为音视频内存接口定义native层对象。 + * @since 9 + */ +typedef struct OH_AVMemory OH_AVMemory; + +/** + * @brief 创建OH_AVMemory实例的指针。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param size 创建内存的大小,单位字节。 + * @return 如果创建成功,返回OH_AVMemory实例的指针,如果失败,返回NULL。 + * 使用结束后需要通过OH_AVMemory_Destroy释放内存。\n + * 可能的失败原因:\n + * 1. size <= 0。\n + * 2. 创建OH_AVMemory失败。\n + * 3.OH_AVMemory内存分配失败。 + * @deprecated since 11 + * @useinstead {@link OH_AVBuffer_Create} + * @since 10 + */ +OH_AVMemory *OH_AVMemory_Create(int32_t size); + +/** + * @brief 获取内存虚拟地址。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param mem 指向OH_AVMemory实例的指针。 + * @return 如果内存有效,返回内存的虚拟地址,如果内存无效,返回NULL。\n + * 可能的失败原因:\n + * 1. 输入mem为空指针。\n + * 2. 输入mem参数结构校验失败。\n + * 3. 输入mem中内存为空指针。 + * @deprecated since 11 + * @useinstead {@link OH_AVBuffer_GetAddr} + * @since 9 + * @version 1.0 + */ +uint8_t *OH_AVMemory_GetAddr(struct OH_AVMemory *mem); + +/** + * @brief 获取内存长度。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param mem 指向OH_AVMemory实例的指针。 + * @return 如果内存有效,返回内存长度,如果内存无效,返回-1。\n + * 可能的失败原因:\n + * 1. 输入mem为空指针。\n + * 2. 输入mem参数结构校验失败。\n + * 3.输入mem中内存为空指针。 + * @deprecated since 11 + * @useinstead {@link OH_AVBuffer_GetCapacity} + * @since 9 + * @version 1.0 + */ +int32_t OH_AVMemory_GetSize(struct OH_AVMemory *mem); + +/** + * @brief 释放OH_AVMemory实例指针的资源。 + * @syscap SystemCapability.Multimedia.Media.Core + * @param mem 指向OH_AVMemory实例的指针。 + * @return AV_ERR_OK:释放成功。\n + * AV_ERR_INVALID_VAL:\n + * 1. 输入mem为空指针。\n + * 2. 输入mem参数结构校验失败。\n + * 3. 输入mem不是开发者创建的。 + * @deprecated since 11 + * @useinstead {@link OH_AVBuffer_Destroy} + * @since 10 + */ +OH_AVErrCode OH_AVMemory_Destroy(struct OH_AVMemory *mem); + +#ifdef __cplusplus +} +#endif + +#endif // NATIVE_AVMEMORY_H + +/** @} */