diff options
-rw-r--r-- | firmware/export/audiohw.h | 104 |
1 files changed, 100 insertions, 4 deletions
diff --git a/firmware/export/audiohw.h b/firmware/export/audiohw.h index acf5fda9f1..e6bb8dc3fc 100644 --- a/firmware/export/audiohw.h +++ b/firmware/export/audiohw.h | |||
@@ -57,6 +57,102 @@ struct sound_settings_info | |||
57 | }; | 57 | }; |
58 | 58 | ||
59 | #undef AUDIOHW_SETTING /* will have been #defined in config.h as empty */ | 59 | #undef AUDIOHW_SETTING /* will have been #defined in config.h as empty */ |
60 | /* Use AUDIOHW_SETTING to create an audio setting. There are two ways to use this | ||
61 | * macro: | ||
62 | * AUDIOHW_SETTING(name, unit, nr_decimals, step, min, max, default) | ||
63 | * AUDIOHW_SETTING(name, unit, nr_decimals, step, min, max, default, expr) | ||
64 | * | ||
65 | * It is important to understand that each setting has two scales: the hardware | ||
66 | * scale and the user scale. In the first form of the macro, they coincide. | ||
67 | * In the second form, the conversion from hardware to user is done by the | ||
68 | * expression [expr] provided in the extra argument (see examples below). The | ||
69 | * hardware scale ranges from [min] to [max], in steps of [step]. The default value | ||
70 | * is [default]. Furthermore, when displaying the value to the user, [nr_decimals] | ||
71 | * gives the number of decimal points to display. Thus if [nr_decimals] is 0 then | ||
72 | * a value of x means x [unit]. If [nr_decimals] is 1 then a value of x means | ||
73 | * x/10 [unit] and so on. Note that both [nr_decimals] and [unit] are irrelevant | ||
74 | * to the hardware, they simply provide a flexible way to show natural value to | ||
75 | * the user. When you want the user scale to be different than the hardware scale, | ||
76 | * you must provide [expr], an expression that can use the variable "val", which | ||
77 | * represents the hardware value, and converts it to the user value. The [expr] | ||
78 | * can involved a function call in very complicated/nonlinear cases, as long as | ||
79 | * the function does not have any side-effect. Finally, the [name] parameter | ||
80 | * must be one of the settings listed in audiohw_setting.h | ||
81 | * | ||
82 | * Examples: | ||
83 | * | ||
84 | * AUDIOHW_SETTING(VOLUME, "dB", 0, 1, -100, 12, -25) | ||
85 | * This describes the volume setting. The values are in dB (no decimal). The | ||
86 | * minimum value is -100 and the maximum is 12, with a step of 1 and a default | ||
87 | * value of -25. This means that the hardware can take any of the following value: | ||
88 | * -100, -99, -98, ..., 11,12 | ||
89 | * Since there is are decimals and no conversion expression, a hardware value of | ||
90 | * x means x dB. So a value of -25 means -25 dB, a value of 5 means 5 dB. | ||
91 | * WARNING VOLUME is actually special: whatever scale you choose, the sound code | ||
92 | * will always set the volume by calling audiohw_set_volume() with a centibel | ||
93 | * value (ie it will not perform any conversion). Thus it is strongly advised | ||
94 | * that you always choose a VOLUME scale with precision 1 (centibels) and no | ||
95 | * hardware conversion. | ||
96 | * | ||
97 | * AUDIOHW_SETTING(MDB_CENTER, "Hz", 0, 10, 20, 300, 60) | ||
98 | * This describes the MDB (dynbamic bass) center. The values are in Hz (no | ||
99 | * decimal). The minimum value is 20 and the maximum is 300, in steps of 10 | ||
100 | * and a default of 60. Thus hardware can take any of the following value: | ||
101 | * 20, 30, 40, ... 290, 300 | ||
102 | * Since there are no decimals and no conversion expression, a hardware of x | ||
103 | * means x Hz. So a value of 60 means 60 Hz. | ||
104 | * | ||
105 | * AUDIOHW_SETTING(BASS, "dB", 1, 15, -60, 90, 0) | ||
106 | * This describes the bass control. Since there is one decimal, the values are | ||
107 | * in tenth of dB. The minimum value is -60 and the maximum is 90, in steps of | ||
108 | * 15 and a default value of 0. Thus hardware can take any of the following value: | ||
109 | * -60, -45, -30, ... 60, 75, 90 | ||
110 | * Since there is one decimal, a hardware value of x means x/10 Hz. So a value | ||
111 | * of 60 means 60/10 = 6 dB. A value of -45 means -45/10 = -4.5 dB. | ||
112 | * | ||
113 | * AUDIOHW_SETTING(DEPTH_3D, "%", 0, 1, 0, 15, 0, (100 * val + 8) / 15) | ||
114 | * This describes 3D enhancement control. The values are in percentage (no | ||
115 | * decimal). This setting makes a difference between hardware and user scale. | ||
116 | * The minimal hardware value is 0 and the maximum is 15, in steps of 1 and | ||
117 | * a default of 0. Thus hardware can take any of the following value: | ||
118 | * 0, 1, 2, ... 14, 15 | ||
119 | * Because of the conversion expression, a hardware value of x means | ||
120 | * (100 * val + 8) / 15) %. A hardware value of 0 means (100 * 0 + 8) / 15) = 0 % | ||
121 | * because the result must be an integer (8 / 15 = 0). A hardware value of 1 | ||
122 | * means (100 * 1 + 8) / 15 = 7 %. A hardware value of 15 means | ||
123 | * (100 * 15 + 8) / 15 = 100 %. In fact, from the user point of view, the range | ||
124 | * of available values is: | ||
125 | * 0%, 7%, 13%, 20%, ..., 93%, 100% | ||
126 | * | ||
127 | * AUDIOHW_SETTING(LEFT_GAIN, "dB", 2, 15,-345, 1200, 0, val * 5) | ||
128 | * This describes the left gain. Since there are two decimals, the values are in | ||
129 | * hundredth of dB. This setting makes a difference between hardware and user scale. | ||
130 | * The minimal hardware value is -345 and the maximum is 1200, in steps of 15 and | ||
131 | * a default of 0. Thus hardware can take any of the following value: | ||
132 | * -345, -330, -315, ..., 1185, 1200 | ||
133 | * Because of the conversion expression, a hardware value of x means | ||
134 | * val * 5 hundredth of dB or, in other words, (val * 5)/100 dB (where we keep two | ||
135 | * decimals). A hardware value of -345 means -345 * 5 = -1725 hundredth of dB | ||
136 | * = -17,25 dB. A value of -330 means -330*5 = -1650 hundredth of dB = -16,50 dB. | ||
137 | * A value of 1200 means 1200 * 5 = 6000 hundredth of dB = 60 dB. In fact, | ||
138 | * from the user point of view, the range of available values is: | ||
139 | * -17.25 dB, -16.60 dB, ..., 59.25 dB, 60dB. | ||
140 | * | ||
141 | * AUDIOHW_SETTING(DEPTH_3D, "dB", 0, 1, 0, 3, 0, depth3d_phys2_val(val)) | ||
142 | * This describes 3D enhancement control. The values are in dB (no | ||
143 | * decimal). This setting makes a difference between hardware and user scale. | ||
144 | * The minimal hardware value is 0 and the maximum is 3, in steps of 1 and | ||
145 | * a default of 0. Thus hardware can take any of the following value: | ||
146 | * 0, 1, 2, 3 | ||
147 | * Because of the conversion expression, a hardware value of x means | ||
148 | * depth3d_phys2_val(x) dB. If for example the conversion functions is: | ||
149 | * int depth3d_phys2_val(int val) | ||
150 | * { | ||
151 | * return val == 0 ? 0 : val * 5 + 30; | ||
152 | * } | ||
153 | * then from the user point of view, the range of available values is: | ||
154 | * 0 dB, 35 dB, 40 dB, 45 dB | ||
155 | */ | ||
60 | #define AUDIOHW_SETTING(name, us, nd, st, minv, maxv, defv, expr...) \ | 156 | #define AUDIOHW_SETTING(name, us, nd, st, minv, maxv, defv, expr...) \ |
61 | static const struct sound_settings_info _audiohw_setting_##name = \ | 157 | static const struct sound_settings_info _audiohw_setting_##name = \ |
62 | { .unit = us, .numdecimals = nd, .steps = st, \ | 158 | { .unit = us, .numdecimals = nd, .steps = st, \ |
@@ -323,7 +419,7 @@ void audiohw_close(void); | |||
323 | #ifdef AUDIOHW_HAVE_MONO_VOLUME | 419 | #ifdef AUDIOHW_HAVE_MONO_VOLUME |
324 | /** | 420 | /** |
325 | * Set new volume value | 421 | * Set new volume value |
326 | * @param val to set. | 422 | * @param val to set in centibels. |
327 | * NOTE: AUDIOHW_CAPS need to contain | 423 | * NOTE: AUDIOHW_CAPS need to contain |
328 | * CLIPPING_CAP | 424 | * CLIPPING_CAP |
329 | */ | 425 | */ |
@@ -331,8 +427,8 @@ void audiohw_set_volume(int val); | |||
331 | #else /* Stereo volume */ | 427 | #else /* Stereo volume */ |
332 | /** | 428 | /** |
333 | * Set new volume value for each channel | 429 | * Set new volume value for each channel |
334 | * @param vol_l sets left channel volume | 430 | * @param vol_l sets left channel volume in centibels. |
335 | * @param vol_r sets right channel volume | 431 | * @param vol_r sets right channel volume in centibels. |
336 | */ | 432 | */ |
337 | void audiohw_set_volume(int vol_l, int vol_r); | 433 | void audiohw_set_volume(int vol_l, int vol_r); |
338 | #endif /* AUDIOHW_HAVE_MONO_VOLUME */ | 434 | #endif /* AUDIOHW_HAVE_MONO_VOLUME */ |
@@ -351,7 +447,7 @@ void audiohw_set_lineout_volume(int vol_l, int vol_r); | |||
351 | || defined(AUDIOHW_HAVE_EQ) | 447 | || defined(AUDIOHW_HAVE_EQ) |
352 | /** | 448 | /** |
353 | * Set new prescaler value. | 449 | * Set new prescaler value. |
354 | * @param val to set. | 450 | * @param val to set in centibels. |
355 | * NOTE: AUDIOHW_CAPS need to contain | 451 | * NOTE: AUDIOHW_CAPS need to contain |
356 | * PRESCALER_CAP | 452 | * PRESCALER_CAP |
357 | */ | 453 | */ |