# 示例代码介绍

本章主要介绍芯片上的功能模块的示例代码，主要包含多媒体硬件加速模块的使用示例。包含单模块功能示例、多模块组合串联示例和应用解决方案示例，用户可以使用这些示例快速完成功能评测，参考其中的实现代码可帮助用户快速上手并开发适合自身需求的应用。

本章介绍的多媒体相关硬件加速模块和他们之间的关系，请查阅 [ 多媒体开发指南 - 系统概述 ](../multimedia_development/0-Overview_zh_CN.md) 。

通过使用本章节提供的示例，用户将能够：

- 理解每个硬件加速模块的基本功能和适用场景。
- 学习如何高效地将多个模块组合，解决实际问题。
- 快速掌握示例代码的使用方法，从而节省开发时间。

## 示例源码目录结构

所有示例代码的源码存放在 BSP 源码的 `app/samples/platform_samples` 目录下。

源码目录结构如下，按照功能和场景进行命名区分。

```
.
├── chip_base_test    # 驱动功能单元测试，请查阅 [ BSP 开发指南 - 驱动功能单元测试 ] 了解使用方法
├── Makefile          # 所有模块的编译总入口（ sunrise_camera 不使用这个 Makefile）
├── Makefile.in       # Makefile 的参数配置，包括交叉编译工具链，头文件、库文件引用等
├── README.md
├── sample_audio      # 基于 ALSA（ Advanced Linux Sound Architecture）库开发的音频录音、播放示例
├── sample_codec      # 视频图像编、解码模块的示例代码，包括 H264\H265\JPEG\MJPEG 的编码和解码
├── sample_crypto     # 通过多个操作示例演示常用安全操作接口的使用方法
├── sample_dsp        # 主要说明如何在芯片上简单的使用 DSP 进行任务处理
├── sample_gdc        # GDC 模块支持的各种转换模式的示例代码
├── sample_gpu_2d     # 2D GPU 支持的各种功能示例代码
├── sample_hbmem      # 本示例介绍一套基于 ION 的内存管理库的 API 使用方法
├── sample_imu        # 本示例是一个用于使用惯导传感器的命令行案例
├── sample_isp        # ISP 模块的示例代码，包括如何初始化 ISP，获取 ISP 处理后的数据，动态设置 ISP 参数等
├── sample_osd        # 介绍如何使用 OSD 功能
├── sample_pipeline   # 串联多功能模块的示例代码，例如： VIN->ISP->VSE->CODEC 编码的数据流通路功能测试
├── sample_usb        # 提供 USB 的 UVC 和 UAC 功能示例
├── sample_trustzone  # TA 和 CA 的简单示例代码
├── sample_vin        # 初始化 Camera Sensor，从 VIN 模块获取图像
├── sample_vot        # 提供基于 DRM 框架的视频图像显示功能
├── sample_vse        # 初始化 VSE 模块，使用 VSE 对图像进行缩放操作
├── sunrise_camera    # 集成大部分模块实现的应用方案示例代码，支持智能摄像头和智能分析盒，在 Web 上可以浏览视频图像和智能算法结果
├── tuning_tool       # ISP 图像效果调试时需要使用到本程序
├── utils             # 包含通用的函数及结构体
└── vp_sensors        # Camera Sensor 配置代码，本代码会被其他需要使用 Camera Sensor 的模块使用
```

注：`vp_sensors` 目录包含已支持的 `Camera Sensor` 和配置文件，不是单独的示例程序。`Camera Sensor` 添加方式请查阅参考 `vp_sensors/README.md`。

## 示例使用指南

所有示例程序、依赖的资源文件，默认安装在开发板的 `/app/platform_samples` 目录下，用户可以直接登录开发板使用这些示例。例如想要使用 sample_vse 示例，可以按照以下命令使用：

```
cd /app/platform_samples/sample_vse

# 执行 sample_vse 获取程序的帮助信息

./sample_vse
Usage: sample_vse [OPTIONS]
Options:
-i, --input_file FILE           Specify the input file
-w, --input_width WIDTH         Specify the input width
-h, --input_height HEIGHT       Specify the input height
-f, --feedback                  Specify feedback mode
-V, --verbose                   Enable verbose mode
```

其他示例都可以按照这种方式使用。

## 示例开发指南

### <span id="sample_build"/> 编译方法

本模块的示例代码在编译时，需要依赖 BSP 源码编译生成的 hbre 头文件、库文件，以及根文件系统中的 ffmpeg 等头文件和动态库。相关路径的引用已在 `Makefile.in` 文件中配置如下：

```
-I ${HR_BUILD_OUTPUT_DIR}/build/hbre_deps/include/
-L ${HR_BUILD_OUTPUT_DIR}/build/hbre_deps/usr/lib
-L ${HR_BUILD_OUTPUT_DIR}/deploy/system/usr/lib
```

因此，在编译本模块代码之前，必须先完成 BSP 的编译，以生成所需的头文件和库文件。有关 BSP 编译的详细方法，请参考 [ 环境搭建及编译说明 ](../linux_development/bsp_develop.md)。

- **整体编译所有示例**

  完成编译整个 BSP ，所有示例代码都会进行编译，并且安装到 BSP 的 `out/deploy/app/platform_samples` 下：

  ```
  ./bd.sh
  ```

- **单个示例编译方法**

  在完成 BSP 的整体编译后，可以对 `app/samples/platform_samples` 中的各示例单独进行开发与编译。以下提供两种编译方法：

  1. **直接进入模块目录编译**

     进入需要编译的模块目录并执行 `make` 命令。例如，单独编译 `sample_vin` 示例：

     ```
     cd samples/platform_samples/sample_vin/get_vin_data
     make
     ```

     直接 make 编译的程序会生成在当前示例的源码目录下，**不会安装** 到 BSP 的 `out/deploy/app/platform_samples` 下。

  2. **通过 BSP 编译框架编译**

     使用 BSP 的编译框架，在 BSP 根目录下执行以下命令即可编译指定示例：

     ```
     ./bd.sh app samples/platform_samples
     ```

​		通过 BSP 提供的编译框架编译的程序不仅会生成在当前示例的源码目录下，而且 **会安装** 到 BSP 的 `out/deploy/app/platform_samples` 下。

## 常见问题

### /app 目录下空间不足导致示例运行失败

**问题原因：** /app 目录是挂载的 app 分区，它的空间有限，我们有些示例程序在运行时需要保存大量的视频图像数据，很容易把空间占满，让程序运行的结果不符合预期。

**解决方法：** 可以把程序拷贝到 /userdata 目录下运行， /userdata 目录下的空间相对 /app 目录会宽裕很多。

### 串口终端登陆的情况下内核日志刷屏

在板端执行以下命令降低 Kernel 的日志输出级别，避免输出日志太多，影响查看程序的执行流程：

```
echo 4 > /proc/sys/kernel/printk
```

