# rgb_player_mgr 模块说明

## 概览

rgb_player_mgr 提供灯效数据管理与播放控制两层能力：
- rgb_effect：灯效数据描述与查找/切换
- rgb_player：基于线程与消息队列的灯效播放与渲染控制

## 文件职责

- rgb_effect.h / rgb_effect.c  
  灯效数据模型与工具函数。负责按名称查找灯效、按帧索引取帧数据、切换下一/上一灯效。

- rgb_player.h / rgb_player.c  
  播放器状态机与线程逻辑。提供打开/关闭播放器、发送事件、渲染帧数据与输出的完整流程。

## 关键数据结构

- rgb_effect_t  
  描述一个灯效：LED 数量、帧间隔、帧数据与步长等。

- rgb_player_msg_t  
  播放器事件消息。承载播放、暂停、切换灯效、固定色与音频律动等事件参数。

- rgb_player_cfg_t  
  播放器配置参数。包含灯效表、帧缓存、输出回调、消息队列、线程与同步对象配置。

- rgb_player_t  
  播放器运行时对象。维护状态、当前灯效、帧索引、线程与 IPC 对象。

## 运行流程

1. 应用初始化配置并调用 rgb_player_open 创建播放器线程与消息队列。  
2. 应用通过 rgb_player_send 发送事件。  
3. 播放器线程接收事件并更新状态或渲染帧。  
4. 在播放状态下，线程根据帧间隔周期渲染并输出。  
5. 调用 rgb_player_close 触发线程退出并释放资源。  

## 事件与行为

- PLAY：进入播放状态并尝试渲染首帧  
- PAUSE：暂停播放（不改变帧索引）  
- STOP：停止播放并清空缓存  
- SET_FORE_EFFECT：设置前景灯效并开始播放  
- SET_BACK_EFFECT：设置背景灯效用于回退播放  
- NEXT_EFFECT / PREV_EFFECT：切换灯效并继续播放  
- SET_LOOP：设置循环播放  
- AUDIO_RHYTHM / SET_FIXED_COLORS：覆盖当前输出为指定帧数据  
- EXIT：线程退出  

## 线程与 IPC

- 消息队列：线程与调用者之间的事件通道  
- 信号量：用于关闭时等待线程退出  
- 输出互斥：可选的输出锁，保证输出回调串行  

## 使用建议

- frame_cache 与 frame_cache_size 必须匹配 LED 数量上限  
- 灯效数组与 effect_count 必须一致  
- 输出回调应为实时安全，避免阻塞  
- 事件驱动统一通过 rgb_player_send，避免并发直接修改 player 结构体  

## 相关文件

- rgb_effect.h  
- rgb_effect.c  
- rgb_player.h  
- rgb_player.c  
