add api for manipulating volume balances

src/map-file

@@ -100,10 +100,12 @@ pa_cvolume_avg;
 pa_cvolume_channels_equal_to;
 pa_cvolume_compatible;
 pa_cvolume_equal;
+pa_cvolume_get_balance;
 pa_cvolume_init;
 pa_cvolume_max;
 pa_cvolume_remap;
 pa_cvolume_set;
+pa_cvolume_set_balance;
 pa_cvolume_snprint;
 pa_cvolume_valid;
 pa_ext_stream_restore_delete;

src/pulse/volume.c

@@ -402,3 +402,94 @@ int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) {
 
     return v->channels == ss->channels;
 }
+
+static void get_avg_lr(const pa_channel_map *map, const pa_cvolume *v, pa_volume_t *l, pa_volume_t *r) {
+    int c;
+    pa_volume_t left = 0, right = 0;
+    unsigned n_left = 0, n_right = 0;
+
+    pa_assert(v);
+    pa_assert(map);
+    pa_assert(map->channels == v->channels);
+    pa_assert(l);
+    pa_assert(r);
+
+    for (c = 0; c < map->channels; c++) {
+        if (on_left(map->map[c])) {
+            left += v->values[c];
+            n_left++;
+        } else if (on_right(map->map[c])) {
+            right += v->values[c];
+            n_right++;
+        }
+    }
+
+    *l = left / n_left;
+    *r = right / n_right;
+}
+
+float pa_cvolume_get_balance(const pa_channel_map *map, const pa_cvolume *v) {
+    pa_volume_t left, right;
+
+    pa_assert(v);
+    pa_assert(map);
+    pa_assert(map->channels == v->channels);
+
+    get_avg_lr(map, v, &left, &right);
+
+    if (left == right)
+        return 0.0f;
+
+    /*   1.0,  0.0  =>  -1.0
+         0.0,  1.0  =>   1.0
+         0.0,  0.0  =>   0.0
+         0.5,  0.5  =>   0.0
+         1.0,  0.5  =>  -0.5
+         1.0,  0.25 => -0.75
+         0.75, 0.25 => -0.66
+         0.5,  0.25 => -0.5   */
+
+    if (left > right)
+        return -1.0f + ((float) right / (float) left);
+    else
+        return 1.0f - ((float) left / (float) right);
+}
+
+pa_cvolume* pa_cvolume_set_balance(const pa_channel_map *map, pa_cvolume *v, float new_balance) {
+    pa_volume_t left, nleft, right, nright, m;
+    unsigned c;
+    pa_assert(map->channels == v->channels);
+
+    pa_assert(map);
+    pa_assert(v);
+    pa_assert(new_balance >= -1.0f);
+    pa_assert(new_balance <= 1.0f);
+
+    get_avg_lr(map, v, &left, &right);
+
+    m = PA_MAX(left, right);
+
+    if (new_balance <= 0) {
+        nright  = (new_balance + 1.0f) * m;
+        nleft = m;
+    } else  {
+        nleft = (1.0f - new_balance) * m;
+        nright = m;
+    }
+
+    for (c = 0; c < map->channels; c++) {
+        if (on_left(map->map[c])) {
+            if (left == 0)
+                v->values[c] = 0;
+            else
+                v->values[c] = (pa_volume_t) (((uint64_t) v->values[c] * (uint64_t) nleft) / (uint64_t) left);
+        } else if (on_right(map->map[c])) {
+            if (right == 0)
+                v->values[c] = 0;
+            else
+                v->values[c] = (pa_volume_t) (((uint64_t) v->values[c] * (uint64_t) nright) / (uint64_t) right);
+        }
+    }
+
+    return v;
+}

src/pulse/volume.h

@@ -233,6 +233,20 @@ pa_cvolume *pa_cvolume_remap(pa_cvolume *v, pa_channel_map *from, pa_channel_map
  * the specified sample spec. \since 0.9.13 */
 int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE;
 
+/** Calculate a 'balance' value for the specified volume with the
+ * specified channel map. The return value will range from -1.0f
+ * (left) to +1.0f (right) \since 0.9.15 */
+float pa_cvolume_get_balance(const pa_channel_map *map, const pa_cvolume *v) PA_GCC_PURE;
+
+/** Adjust the 'balance' value for the specified volume with the
+ * specified channel map. v will be modified in place and
+ * returned. The balance is a value between -1.0f and +1.0f. This
+ * operation might not be reversable! Also, after this call
+ * pa_cvolume_get_balance() is not guaranteed to actually return the
+ * requested balance (e.g. when the input volume was zero anyway for
+ * all channels)- \since 0.9.15 */
+pa_cvolume* pa_cvolume_set_balance(const pa_channel_map *map, pa_cvolume *v, float new_balance);
+
 PA_C_DECL_END
 
 #endif

src/tests/voltest.c

@@ -6,6 +6,8 @@
 int main(int argc, char *argv[]) {
     pa_volume_t v;
     pa_cvolume cv;
+    float b;
+    pa_channel_map map;
 
     for (v = PA_VOLUME_MUTED; v <= PA_VOLUME_NORM*2; v += 256) {
 
@@ -28,5 +30,32 @@ int main(int argc, char *argv[]) {
 
     }
 
+    map.channels = cv.channels = 2;
+    map.map[0] = PA_CHANNEL_POSITION_LEFT;
+    map.map[1] = PA_CHANNEL_POSITION_RIGHT;
+
+    for (cv.values[0] = PA_VOLUME_MUTED; cv.values[0] <= PA_VOLUME_NORM*2; cv.values[0] += 4096)
+        for (cv.values[1] = PA_VOLUME_MUTED; cv.values[1] <= PA_VOLUME_NORM*2; cv.values[1] += 4096) {
+            char s[PA_CVOLUME_SNPRINT_MAX];
+
+            printf("Volume: [%s]; balance: %2.1f\n", pa_cvolume_snprint(s, sizeof(s), &cv), pa_cvolume_get_balance(&map, &cv));
+        }
+
+    for (cv.values[0] = PA_VOLUME_MUTED+4096; cv.values[0] <= PA_VOLUME_NORM*2; cv.values[0] += 4096)
+        for (cv.values[1] = PA_VOLUME_MUTED; cv.values[1] <= PA_VOLUME_NORM*2; cv.values[1] += 4096)
+            for (b = -1.0f; b <= 1.0f; b += 0.2f) {
+                char s[PA_CVOLUME_SNPRINT_MAX];
+                pa_cvolume r;
+                float k;
+
+                printf("Before: volume: [%s]; balance: %2.1f\n", pa_cvolume_snprint(s, sizeof(s), &cv), pa_cvolume_get_balance(&map, &cv));
+
+                r = cv;
+                pa_cvolume_set_balance(&map, &r, b);
+
+                k = pa_cvolume_get_balance(&map, &r);
+                printf("After: volume: [%s]; balance: %2.1f (intended: %2.1f) %s\n", pa_cvolume_snprint(s, sizeof(s), &r), k, b, k < b-.05 || k > b+.5 ? "MISMATCH" : "");
+            }
+
     return 0;
 }