根据孵化意见修改readme

Signed-off-by: ulimax_001 <wangwei234@huawei.com>
This commit is contained in:
ulimax_001
2026-02-04 19:40:43 +08:00
parent c7302afb90
commit 6ce37e54ea
2 changed files with 203 additions and 108 deletions
+105 -55
View File
@@ -1,70 +1,81 @@
# dav1d
Original Repositoryhttps://code.videolan.org/videolan/dav1d
# dav1d in OpenHarmony
## Overview
The repository includes the third-party open-source software dav1d, which is a video codec implementation for the AV1 standard. In OpenHarmony, dav1d serves as a fundamental component of the media subsystem, providing AV1 stream decoding capabilities for AVCodec.
The repository includes the third-party open-source software dav1d, which is a video codec implementation for the AV1 standars. In OpenHarmony, dav1d serves as a fundamental component of the media subsystem, providing AV1 stream decoding capabilities for AVCodec.
Original Repositoryhttps://code.videolan.org/videolan/dav1d
## Directory Structure
```
//third_party_dav1d
|-- BUILD.gn # GN build configuration file, defines build rules and dependencies. Added by OpenHarmony
|-- bundle.json # Component package configuration file, describes component information and dependencies. Added by OpenHarmony
|-- BUILD.gn # GN build configuration file, defines build rules and dependencies.
|-- bundle.json # Component package configuration file, describes component information and dependencies.
|-- doc # Project documentation directory
|-- examples # Example code directory
|-- include # Header files directory
|-- package # Package-related files directory
|-- src # Source code directory
|-- tests # Test code directory
|-- tools # Tools and utilities directory
```
## How to Use dav1d in OpenHarmony
System components in OpenHarmony need to reference the dav1d component in BUILD.gn to use it.
|-- tools # Utility tools directory
```
## Compliance Requirements
According to the OpenHarmony PCS ([Product Compatibility Specification](https://www.openharmony.cn/systematic)):
(1) If AV1 decoding is supported, the recommended AV1 decoding capability is at least 1080p (Main Profile (8bit, 10bit), High Profile(8bit, 10bit), Level 4.0).
## Using dav1d in OpenHarmony
The AVCodec component provides OpenHarmony with a unified video decoding capability. Refer to the [AVCodec Architecture Diagram](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/README_zh.md) for an overview.
Specifically
(1) The framework layer exposes APIs to application developers: [obtain supported codecs](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/media/avcodec/obtain-supported-codecs.md) [checking the codec profile and level supported](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/media/avcodec/obtain-supported-codecs.md#checking-the-codec-profile-and-level-supported)。
(2) In the service layer, the software decoder module wraps the dav1d.
### Build Configuration
(1) The `AVCodec` component integrates and utilizes the AV1 decoding capabilities of the `dav1d` component by referencing it in its BUILD.gn file:
```gn
// BUILD.gn
external_deps + = [dav1d:dav1d_ohos]
external_deps += ["dav1d:dav1d_ohos"]
```
## Feature Support
**Since** 6.1
(1) When the application attempt to create a decoder according to the [platform rules](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/media/avcodec/avcodec-support-formats.md), the system preferentially creates a hardware decoder instance. If the system does not support hardware decoding or the hardware decoder resources are insufficient, the system creates a software decoder instance.
(2) AV1 software decoding is an optional capability in OpenHarmony. you can enable/disable the feature via your own product configuration. The product configuration path can be as follows:
```
//vendor/${pruduct_company}/${product_name}/config.json
```
The configuration can be set as shown below:
```json
"multimedia:av_codec": {
"features": {
"av_codec_support_av1_decoder": false,
}
(2) The `AVCodec` component declares the feature `av_codec_support_av1_decoder` in its [bundle.json](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/bundle.json). This feature is initialized in [Config.gni](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/config.gni) as follows:
```gn
declare_args() {
av_codec_support_av1_decoder = true // Setting it to true enables AV1 soft decoding by default
}
```
(3) According to the OpenHamony PCS ([Product Compatibility Specification](https://www.openharmony.cn/systematic)), If AV1 decoding is supported, the recommended AV1 decoding capability is at least 1080p(Main Profile(8bit、10bit)、High Profile(8bit、10bit),level 4.0). You can modify the supported Profile and Level in the AVCodec, the path is as follows
### Decoder Creation
```
//foundation/multimedia/avcodec/services/engine/codec/video/av1decoder/av1decoder.cpp
+------------------+ +-----------------------------+
| CodecServer |----->| CodecFactory |
+------------------+ +-----------------------------+
| - codec:CodecBase| | + createByName():CodecBase |
+------------------+ +-----------------------------+
| calls static method createByName()
+--------v----------+
| AV1DecoderLoader |
+-------------------+
| + createByName() |
| :CodecBase |
+--------|----------+
| inherit
+---------▼-----------+
| VideoCodecLoader |
+---------------------+
| use
+-------v---------+
| CodecBase |
+-------▲---------+
| implement
+-----------------+
| AV1Decoder |
+-----------------+
Figure 1: AVCodec AV1Decoder creation process
```
and the function:
```C++
void Av1Decoder::GetCodecCapability(std::vector<CapabilityData> &capaArray)
{
...
CapabilityData capsData;
...
// Assign supported profilese.g., AV1 Main ProfileHigh Profile
capsData.profile = {
static_cast<int32_t>(AV1_PROFILE_MAIN),
static_cast<int32_t>(AV1_PROFILE_HIGH)
};
std::vector<int32_t> levels
// Assign supported levels for the profilee.g., level 4.0
for (int32_t j = 0; j <= static_cast<int32_t>(AV1Level::AV1_LEVEL_4_0); j++) {
levels.emplace_back(j);
}
capsData.profileLevelsMap.insert({static_cast<int32_t>(AV1_PROFILE_MAIN), levels});
...
capaArray.emplace_back(capsData);
}
```
According to the AV1 standard, the above Profiles and Levels are fully defined in [avcodec_info.h](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/inner_api/native/avcodec_info.h):
(1) In the AVCodec service layer, CodecServer uses [CodecFactory](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/services/services/codec/server/video/codec_factory.cpp) to invoke the static method CreateByName() of AV1DecoderLoader, which creates an AV1 decoder(`AV1Decoder`).
(2) `AV1Decoder` is a wrapper around the AV1 decoder from **dav1d**. It also provides a capability query function, GetCodecCapability(std::vector<CapabilityData>& capaArray), which reports the supported capabilities such as Profile and Level.
(3) The Profiles and Levels are fully defined in [avcodec_info.h](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/inner_api/native/avcodec_info.h):
```C
enum AV1Profile : int32_t {
AV1_PROFILE_MAIN = 0,
@@ -81,7 +92,7 @@ enum AV1Level : int32_t {
AV1_LEVEL_73 = 23,
};
```
If application developers need to be aware of them, the definitions must also be included in both the [SDK](https://gitcode.com/openharmony/interface_sdk_c/blob/master/multimedia/av_codec/native_avcodec_base.h) and [AVCodec](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/kits/c/native_avcodec_base.h):
Additionally, Profile and Level are exposed in native_avcodec_base.h in both [SDK](https://gitcode.com/openharmony/interface_sdk_c/blob/master/multimedia/av_codec/native_avcodec_base.h) and [AVCodec](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/kits/c/native_avcodec_base.h). These definitions serve as the public API for application developers.
```C
typedef enum OH_AV1Profile {
AV1_PROFILE_MAIN = 0,
@@ -98,11 +109,50 @@ typedef enum OH_AV1Level {
AV1_LEVEL_73 = 23,
} OH_AV1Level;
```
Full documentation is available:[OH_AV1Profile](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1profile), [OH_AV1level](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1level).
Full documentation is available:[OH_AV1Profile](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1profile), [OH_AV1level](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1level).
In addition, if support for the Professional Profile (12-bit) is required, the display system (specifically SurfaceBuffer) must support 12-bit color depth.
## Vendor Customization
(1) AV1 software decoding is an optional capability in OpenHarmony. You can enable or disable AV1 software decoding via product-specific configuration. The configuration file can be locate at:
(4) Application developers can query the above configurations and capabilities through the AVCodec interface. see [Obtaining Supported Codecs](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/media/avcodec/obtain-supported-codecs.md#obtaining-supported-codecs), [Checking the Codec Profile and Level Supported](https://gitcode.com/openharmony/docs/blob/master/en/application-dev/media/avcodec/obtain-supported-codecs.md#checking-the-codec-profile-and-level-supported).
//vendor/${product_company}/${product_name}/config.json
The configuration can be set as shown below: set `av_codec_support_av1_decoder` to true to enable AV1 software decoding, or false to disable it:
```json
"multimedia:av_codec": {
"features": {
"av_codec_support_av1_decoder": false, // AV1 software decoding is disabled
}
}
```
(2) Vendors may adjust the supported AV1 Profile and Level according to the devices CPU performance and system capabilities by modifying the values assigned to the output parameter capaArray in the GetCodecCapability function in the source code below:
//foundation/multimedia/av_codec/services/engine/codec/video/av1decoder/av1decoder.cpp
```cpp
void Av1Decoder::GetCodecCapability(std::vector<CapabilityData> &capaArray)
{
...
CapabilityData capsData;
...
// Assign supported profiles, e.g., AV1 Main Profile, High Profile
capsData.profile = {
static_cast<int32_t>(AV1_PROFILE_MAIN),
static_cast<int32_t>(AV1_PROFILE_HIGH)
};
std::vector<int32_t> levels;
// Emplace supported levels for Main Profile (e.g., up to Level 4.0)
for (int32_t j = 0; j <= static_cast<int32_t>(AV1Level::AV1_LEVEL_40); j++) {
levels.emplace_back(j);
}
capsData.profileLevelsMap.insert({static_cast<int32_t>(AV1_PROFILE_MAIN), levels});
...
capaArray.emplace_back(capsData);
}
```
If support for the Main Profile(10-bit), High Profile(10-bit) and Professional profile(10-bit, 12-bit) are required, the graphics system (specifically SurfaceBuffer) must support 10-bit and 12-bit color depth.
(3) Additionally, for hardware decoding:
In the service layer, CodecFactory invokes the static method CreateByName() of HCodecLoader to create HCodec/HCodecList, which then interact with the HAL/hardware decoder through the HDI. Vendors must implement and adapt their hardware decoders to comply with the requirements of the HDI interface.
## License
See the LICENSE file in the root directory for details.
For license details, see the LICENSE file in the root directory for details.
+98 -53
View File
@@ -1,12 +1,15 @@
# dav1d
原始仓来源:https://code.videolan.org/videolan/dav1d
# third_party_dav1d
## 概述
本文档适用于OpenHarmony 6.1及以上版本。
仓库包含第三方开源软件dav1ddav1d是AV1标准的视频解码器。在OpenHarmony中,dav1d主要媒体子系统的基础组件,为AVCodec提供AV1码流的解码能力。
仓库集成第三方开源软件dav1d(AV1标准的视频解码器的开源实现)。在OpenHarmony中,dav1d主要作为媒体子系统的基础组件,为AVCodec提供AV1码流的解码能力。
dav1d来源:https://code.videolan.org/videolan/dav1d
## 目录结构
```
//third_party_dav1d
|-- BUILD.gn # GN构建配置文件,定义编译规则和依赖关系。由OpenHarmony增加
|-- bundle.json # 组件包配置文件,描述组件信息和依赖。由OpenHarmony增加
|-- BUILD.gn # GN构建配置文件,定义编译规则和依赖关系。
|-- bundle.json # 组件包配置文件,描述组件信息和依赖。
|-- doc # 项目文档目录
|-- examples # 示例代码目录
|-- include # 头文件目录
@@ -15,58 +18,63 @@
|-- tests # 测试代码目录
|-- tools # 工具程序目录
```
## OpenHarmony对解码器的要求
根据[OpenHarmony产品兼容性规范](https://www.openharmony.cn/systematic)
## OpenHarmony如何集成dav1d
OpenHarmony通过部件AVCodec集成了dav1d的解码能力,即系统部件可通过BUILD.gn文件引用dav1d部件,以集成并使用其解码能力,方式如下:
(1) 若支持AV1软件解码时,AV1解码建议规格至少为1080p (Main Profile(8bit、10bit)、High Profile(8bit、10bit) Level 4.0)。
## OpenHarmony如何使用dav1d
部件AVCodec为OpenHarmony提供了统一的视频解码能力,参考[AVCodec 框架图](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/README_zh.md),其中:
(1) 框架层的编解码框架对应用开发者提供接口,例如:[获取支持的编解码能力](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/media/avcodec/obtain-supported-codecs.md) [查询编解码档次和级别支持情况](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/media/avcodec/obtain-supported-codecs.md#%E6%9F%A5%E8%AF%A2%E7%BC%96%E8%A7%A3%E7%A0%81%E6%A1%A3%E6%AC%A1%E5%92%8C%E7%BA%A7%E5%88%AB%E6%94%AF%E6%8C%81%E6%83%85%E5%86%B5)。
(2) 服务层中的软件解码器模块将对dav1d进行加载和封装。
### 集成与配置
(1) 部件AVCodec通过BUILD.gn文件引用部件dav1d,以集成并使用其AV1的解码能力。
```
// BUILD.gn
external_deps + = [dav1d:dav1d_ohos]
external_deps += ["dav1d:dav1d_ohos"]
```
## 功能支持说明
**以下说明适用起始版本:** 6.1
(1) 应用在创建AV1解码器时,按照[平台统一规则](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/media/avcodec/avcodec-support-formats.md)系统会优先创建硬件解码器,如无硬件解码器或则硬件解码器资源不足时创建软件解码器(当前AVCodec尚不支持AV1的硬解),如无解码能力则创建失败。
(2) AV1软解码为OpenHamony中的可选能力。厂商可通过配置文件开关AV1的软解码,配置文件路径可以如下:
(2) 部件AVCodec在[bundle.json](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/bundle.json)里声明的featuresav_codec_support_av1_decoder用于使能AV1软解码,并在[Config.gni](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/config.gni)中做了初始化,方式如下:
```
//vendor/${pruduct_company}/${product_name}/config.json
```
配置方式可以如下,在av_codec部件节点的features中配置av_codec_support_av1_decoder
```json
"multimedia:av_codec": {
"features": {
"av_codec_support_av1_decoder": false,
}
declare_args() {
av_codec_support_av1_decoder = true // true表示默认开启AV1软解码
}
```
(3) 按[Openharmony产品兼容性规范](https://www.openharmony.cn/systematic),若支持AV1软件解码时,AV1解码建议规格至少为1080p(Main Profile(8bit、10bit)、High Profile(8bit、10bit) Level 4.0)。厂商可以在AVCodec源码中修改AV1支持的Profile与Level,路径如下:
### 实现及调用
```
//foundation/multimedia/avcodec/services/engine/codec/video/av1decoder/av1decoder.cpp
+------------------+ +-----------------------------+
| CodecServer |----->| CodecFactory |
+------------------+ +-----------------------------+
| - codec:CodecBase| | + createByName():CodecBase |
+------------------+ +-----------------------------+
| 调用静态方法
+--------v----------+
| AV1DecoderLoader |
+-------------------+
| + createByName() |
| :CodecBase |
+--------|----------+
| 继承
+---------▼-----------+
| VideoCodecLoader |
+---------------------+
| 使用
+-------v---------+
| CodecBase |
+-------▲---------+
| 实现
+-----------------+
| AV1Decoder |
+-----------------+
图1 AVCodec服务层AV1软件解码器创建示意图
```
在GetCodecCapability函数中,修改对出参capaArray(成员profileLevelsMap记录支持情况)的赋值,完成后重新编译:
```C++
void Av1Decoder::GetCodecCapability(std::vector<CapabilityData> &capaArray)
{
...
CapabilityData capsData;
...
// 赋值支持的profile,例如支持AV1 Main ProfileHigh Profile
capsData.profile = {
static_cast<int32_t>(AV1_PROFILE_MAIN),
static_cast<int32_t>(AV1_PROFILE_HIGH)
};
std::vector<int32_t> levels
// 赋值profile下支持的level,例如Main Profile支持到level 4.0
for (int32_t j = 0; j <= static_cast<int32_t>(AV1Level::AV1_LEVEL_4_0); j++) {
levels.emplace_back(j);
}
capsData.profileLevelsMap.insert({static_cast<int32_t>(AV1_PROFILE_MAIN), levels}); // 赋值profile下支持的level
...
capaArray.emplace_back(capsData);
}
```
上述Profile和Level均按照AV1标准进行了完整的定义,在AVCodec仓的[avcodec_info.h](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/inner_api/native/avcodec_info.h)中:
(1) AVCodec服务层中CodecServer通过[CodecFactory](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/services/services/codec/server/video/codec_factory.cpp),调用AV1DecoderLoader的静态方法CreateByName()创建AV1的解码器(`AV1Decoder`)。
(2) `AV1Decoder`即是对**dav1d**中AV1解码器的封装,实现能力查询函数GetCodecCapability(std::vector<CapabilityData> &capaArray),即实现对包括Profile与Level在内的能力信息查询。
(3) AVCodec仓的[avcodec_info.h](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/inner_api/native/avcodec_info.h)中对Profile和Level进行了完整的定义:
```C
enum AV1Profile : int32_t {
AV1_PROFILE_MAIN = 0,
@@ -83,7 +91,7 @@ enum AV1Level : int32_t {
AV1_LEVEL_73 = 23,
};
```
若需要应用开发者感知,还需要同时在[SDK仓](https://gitcode.com/openharmony/interface_sdk_c/blob/master/multimedia/av_codec/native_avcodec_base.h)和[AVCodec仓](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/kits/c/native_avcodec_base.h)的native_avcodec_base.h中定义:
同时在[SDK仓](https://gitcode.com/openharmony/interface_sdk_c/blob/master/multimedia/av_codec/native_avcodec_base.h)和[AVCodec仓](https://gitcode.com/openharmony/multimedia_av_codec/blob/master/interfaces/kits/c/native_avcodec_base.h)的native_avcodec_base.h中定义了Profile和Level,作为应用开发者的接口,详细描述见[OH_AV1Profile](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1profile)[OH_AV1level](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1level):
```C
typedef enum OH_AV1Profile {
AV1_PROFILE_MAIN = 0,
@@ -100,11 +108,48 @@ typedef enum OH_AV1Level {
AV1_LEVEL_73 = 23,
} OH_AV1Level;
```
完整的定义描述可见[OH_AV1Profile](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1profile)[OH_AV1level](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcodec-base-h.md#oh_av1level)
另外,若厂商需要支持professional profile(12bit)时,需要OH显示系统(中surfaceBuffer)支持12bit。
## 能力定制说明
(1) AV1软解码为OpenHarmony中的可选能力。厂商可通过配置文件使能,配置文件路径可以如下:
```
//vendor/${product_company}/${product_name}/config.json
```
配置方式可以如下,在av_codec部件节点的features中配置av_codec_support_av1_decoder, 值为true表示开启,false表示关闭:
```json
"multimedia:av_codec": {
"features": {
"av_codec_support_av1_decoder": false, // 设置false为关闭AV1软解码
}
}
```
(2) 厂商可根据自身的CPU性能及系统能力修改AV1支持的Profile与Level,即在如下源码中,修改函数GetCodecCapability出参capaArray的赋值,完成后需重新编译相关组件,可通过[OH_AVCapability_GetSupportedProfiles](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcapability-h.md#oh_avcapability_getsupportedprofiles)[OH_AVCapability_GetSupportedLevelsForProfile](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-avcodec-kit/capi-native-avcapability-h.md#oh_avcapability_getsupportedlevelsforprofile)接口获取实际支持的Profile与Level情况来验证:
```
//foundation/multimedia/av_codec/services/engine/codec/video/av1decoder/av1decoder.cpp
```
```cpp
void Av1Decoder::GetCodecCapability(std::vector<CapabilityData> &capaArray)
{
...
CapabilityData capsData;
...
// 配置支持的Profile,例如支持AV1 Main ProfileHigh Profile
capsData.profile = {
static_cast<int32_t>(AV1_PROFILE_MAIN),
static_cast<int32_t>(AV1_PROFILE_HIGH)
};
std::vector<int32_t> levels;
// 为Profile设置支持的Level范围,例如为Main Profile最高支持到Level 4.0
for (int32_t j = 0; j <= static_cast<int32_t>(AV1Level::AV1_LEVEL_40); j++) {
levels.emplace_back(j);
}
capsData.profileLevelsMap.insert({static_cast<int32_t>(AV1_PROFILE_MAIN), levels}); // 能力信息写入输出参数
...
capaArray.emplace_back(capsData);
}
```
注:配置Main Profile(10-bit), High Profile(10-bit)和Professional Profile(10-bit, 12-bit)时,依赖OH图形系统(的SurfaceBuffer)支持10-bit和12-bit,否则会出现内存申请失败导致解码器初始化失败。
(4) 厂商适配了上述开关及能力后,应用开发者都可以通过AVCodec的接口查询到。详见[获取支持的编解码能力](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/media/avcodec/obtain-supported-codecs.md) [查询编解码档次和级别支持情况](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/media/avcodec/obtain-supported-codecs.md#%E6%9F%A5%E8%AF%A2%E7%BC%96%E8%A7%A3%E7%A0%81%E6%A1%A3%E6%AC%A1%E5%92%8C%E7%BA%A7%E5%88%AB%E6%94%AF%E6%8C%81%E6%83%85%E5%86%B5)
(3) 另外,dav1d仅适用于软解解码。对`硬件解码`场景:服务层CodecFactory调用`HCodecLoader`的静态方法CreateByName()创建HCodec/HCodecList,它们通过HDI接口调用HAL或硬件解码器,厂商需适配并满足`HDI`接口的要求
## License
见仓库目录下的LICENSE文件
具体许可条款请参见仓库目录下的 LICENSE 文件