forked from PAWPAW/lib_rgb
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# RGB灯条驱动库
|
||
|
||
<img src="https://img.pawpaw.cn:4430/assets/1699707514504RmN8t1mh.jpeg" alt="_453de8b7-7edc-4efc-94c3-809a46000e66" style="zoom:50%;" />
|
||
|
||
## 简介
|
||
`lib_rgb` 是一个用于控制RGB灯条的C语言库，提供了一系列功能，比如颜色渐变、呼吸灯效果和色调循环等。它支持通过RGB和HSV颜色空间来控制灯条的颜色输出。
|
||
|
||
## 功能
|
||
|
||
### 组件
|
||
|
||
| 功能 | 示例 | 备注 |
|
||
| ------------ | ------------------------------------ | ------------------------------------------------------------ |
|
||
| **颜色渐变** | `app_rgb_cycle_breathing_example` | 通过逐步调整RGB值来模拟呼吸灯效果。 |
|
||
| **色调循环** | `app_hsv_cycle_example` | 在HSV颜色空间中循环改变色调以实现颜色渐变。 |
|
||
| **颜色转换** | `app_test_HSV_to_RGB` | 将HSV颜色值转换为RGB颜色值。 |
|
||
| **颜色填充** | `app_test_fill_gradient_with_groups` | 将单一颜色填充到整个RGB条中，也可以将RGB条分组，同时输出不同的颜色或响应。 |
|
||
| **幻彩渐变** | `app_hsv_cycle_per_rgb_example` | 每个灯珠独立的HSV渐变，以获得颜色流动的效果。 |
|
||
|
||
### 高级应用
|
||
|
||
| 功能 | 示例 | 备注 |
|
||
| -------------------------- | --------------------------------------- | ----------------------------------------------------- |
|
||
| **响度可视化** | 待补充 | 通过检测音频样本中的响度，实现RGB跟随音量大小跳动 |
|
||
| **色调循环&音量响应** | `app_cycleHSV_vol_level_example` | 根据响度值(-xdB~0dB)，获取音量等级。 |
|
||
| **平滑&音量响应** | `app_vol_level_smooth_example` | 一种过渡效果，当响度下降时，逐级熄灭RGB，而不是突变。 |
|
||
| **平滑&色调循环&音量响应** | `app_cycleHSV_vol_level_smooth_example` | 结合了HSV颜色渐变，平滑过渡，以及音量响应 |
|
||
|
||
## 使用方法
|
||
|
||
### 包含头文件
|
||
|
||
在你的项目中包含`rgb_effect.h`文件，它是较高等级的灯效头文件，用于实现各种灯效，以及向RGB输出灯效
|
||
|
||
```c
|
||
#include "rgb_effect.h"
|
||
```
|
||
|
||
或者直接包含`visualize_volume.h`，它是最高等级的应用头文件，用于实现可视化的响度。你需要为它创建一个线程，并向它的缓存中写入音频样本，以驱动RGB。
|
||
|
||
```c
|
||
#include "visualize_volume.h"
|
||
```
|
||
|
||
//TODO: 后续我们会创建一个例程，帮助你快速构建一个线程安全的应用。
|
||
|
||
### 快速开始
|
||
|
||
如果你想要尝试开箱即用的持续的颜色渐变效果，可以使用`examples/app_hsv_cycle_example/src/hsv_cycle_example.c`中的`hsv_cycle_example`函数，具体的用法可以参考该示例。
|
||
|
||
注意：当前用于驱动LED组的默认的IO，定义在`Tile[1]`的`4A3`端口上，因此你需要添加对tile的声明。
|
||
|
||
```c
|
||
#include <platform.h> // 包含对封装的定义，引用以使用 on tile[] 语法
|
||
|
||
extern "C"
|
||
{
|
||
void hsv_cycle_example();
|
||
}
|
||
|
||
int main() // 定义主函数
|
||
{
|
||
par
|
||
{
|
||
on tile[1]:
|
||
{
|
||
hsv_cycle_example();
|
||
}
|
||
}
|
||
return 0; // 返回0，表示程序正常结束
|
||
}
|
||
|
||
```
|
||
|
||
### 初始化颜色和方向
|
||
|
||
在使用颜色渐变或色调循环功能之前，需要初始化一个颜色值和渐变方向。由于灯条的默认颜色排列为GRB，因此你需要注意颜色的顺序。
|
||
|
||
```c
|
||
uint32_t color = 0x00FF00; // 红色
|
||
GradientDirection direction = INCREMENTING; // 开始时亮度递增
|
||
```
|
||
|
||
### 调用颜色渐变函数
|
||
使用`cycleRGB`函数来实现呼吸灯效果。
|
||
|
||
```c
|
||
uint32_t new_color = cycleRGB(color, &direction);
|
||
```
|
||
|
||
### 调用色调循环函数
|
||
使用`cycleHSV`函数在HSV颜色空间中循环改变色调。
|
||
|
||
```c
|
||
uint32_t hue = 0; // 色调初始化
|
||
uint32_t new_color = cycleHSV(&hue);
|
||
```
|
||
|
||
### 输出颜色到RGB灯条
|
||
使用`output_rgb_array`函数将颜色数组输出到RGB灯条。
|
||
|
||
```c
|
||
uint32_t rgb_array[] = {0x00FF00, 0xFF0000, 0x0000FF}; // 红绿蓝
|
||
output_rgb_array(rgb_array, 3);
|
||
```
|
||
|
||
## 注意事项
|
||
- 该库假设使用的是一个链式单向传递Address数据的RGB LED灯条，并默认适配 *瑞飞2121 RT23-RGBCSH-I3W1-12* ，如果你的灯条有不同的配置，可能需要适当修改代码。
|
||
- `lib_rgb`库中的一些函数包含无限循环，确保你的系统有适当的机制来安全地退出或中断执行。
|
||
|
||
## 路线图
|
||
|
||
- [x] 为绘制RGB的函数添加可合并选项，以减少资源占用
|
||
- [x] 添加更多应用光效
|
||
- [x] RGB渐变
|
||
- [x] HSV渐变
|
||
- [x] 每个灯珠独立的HSV渐变
|
||
- [x] 音频响度响应
|
||
- [ ] 使用fp/s32以增加`HSV_to_RGB`的计算效率
|
||
- [ ] 提供音频响度响应的例程与说明
|
||
|
||
## 贡献
|
||
如果你有任何改进意见或者发现了bug，请通过issues或pull requests来提交或贡献。
|
||
|
||
感谢使用`lib_rgb`！ |