添加API说明

- 添加了RGB灯组的宏说明

lib_rgb/api/rgb_effect.h

@@ -44,11 +44,40 @@ uint32_t cycleRGB(uint32_t color, GradientDirection *direction);
 uint32_t cycleHSV(uint32_t *hue);
 
 /**
- * 将HSV颜色值转换为RGB颜色值。
+ * 将HSV颜色空间转换为RGB颜色空间。
  *
  * 此函数接受HSV（色相、饱和度、亮度）颜色空间的值，并将其转换为RGB（红、绿、蓝）颜色空间的值。
  * 转换过程中，可能会执行有效性检查（取决于HSV_VALID_CHECK预处理器变量）。
  *
+ * 实现步骤：
+ * 1. **规范化色调值：**
+ *    $ H' = \frac{H}{360} $
+ *
+ * 2. **计算色度(Chroma)：**
+ *    $ C = S \times V $
+ *
+ * 3. **计算X值：**
+ *    $ X = C \times (1 - |(H' \times 6) \mod 2 - 1|) $
+ *
+ * 4. **计算中间RGB值：**
+ *    根据H'的值，我们有：
+ *    - 如果 $( 0 \leq H' < 1 )$：$ R1 = C, G1 = X, B1 = 0 $
+ *    - 如果 $( 1 \leq H' < 2 )$：$ R1 = X, G1 = C, B1 = 0 $
+ *    - 如果 $( 2 \leq H' < 3 )$：$ R1 = 0, G1 = C, B1 = X $
+ *    - 如果 $( 3 \leq H' < 4 )$：$ R1 = 0, G1 = X, B1 = C $
+ *    - 如果 $( 4 \leq H' < 5 )$：$ R1 = X, G1 = 0, B1 = C $
+ *    - 如果 $( 5 \leq H' < 6 )$：$ R1 = C, G1 = 0, B1 = X $
+ *
+ * 5. **计算最终RGB值：**
+ *    $ R' = (R1 + (V - C)) \times 255 $
+ *    $ G' = (G1 + (V - C)) \times 255 $
+ *    $ B' = (B1 + (V - C)) \times 255 $
+ *
+ * 6. **限制最终值范围：**
+ *    $ R'' = \min(\max(R', 0), 255) $
+ *    $ G'' = \min(\max(G', 0), 255) $
+ *    $ B'' = \min(\max(B', 0), 255) $
+ * 
  * \param hue    指向色相值的指针，色相值的范围通常是0-360。
  * \param sat    指向饱和度值的指针，饱和度值的范围通常是0-100。
  * \param value  指向亮度值的指针，亮度值的范围通常是0-100。

lib_rgb/src/rgb_effect.xc

@@ -13,17 +13,20 @@
 #define NUM_RGBS           (12)
 #endif
 
+// RGB灯组的数量，不应超过NUM_RGBS
 #ifndef NUM_RGB_GROUPS
 #define NUM_RGB_GROUPS     (2)
 #endif
-// 控制RGB亮度的最大值,不超过255
+
+// 控制RGB亮度的最大值，不超过255
 #ifndef RGB_MAX
 #define RGB_MAX            (20)
 #endif
 
-// 开关饱和检查
+// TODO:优化为编译时检查？
+// 开关饱和检查，该检查会引入性能损失，在需要高刷新率时关闭它
 #ifndef HSV_VALID_CHECK
-#define HSV_VALID_CHECK    (0)
+#define HSV_VALID_CHECK    (1)
 #endif
 
 // 控制HUE的最大值，不超过360°
@@ -47,7 +50,7 @@
 #define DELAY_TIME_RGB     (1000 / RGB_MAX) 
 #endif                                  
 
-// TODO: 当RGB_MAX等值超限时，raise error
+// TODO:当RGB_MAX等值超限时，raise error
 // 定义一个枚举来表示渐变方向
 typedef enum
 {