[C Api] Documentation inconsistencies & General Crashing Issues

[ogniK5377]

Last few weeks I've spent the time updating a beta version of steam audio to the latest stable and there are a few things I wanted to bring up which stomped me with the implementation.

Lack of errors/feedback from simulation/baking

Under certain circumstances, simulations can fail or throw an exception within phonon without a clear indication of why it happens or what caused it. An example of this is attempting to bake a path without a probe batch. This ends up causing an exception within phonon without any feedback on why it happens.

Inability to fetch specific probe data within a probe batch

Currently, if we need to fetch any information about a probe within a probe batch, there's no way to do this. We're able to fetch how many probes themselves exist within the batch, but we cannot any individual probes. In contrast, with a probe array, we're able to fetch information about any probe within it. This means to keep compatibility between versions we need to store a copy of all probes within our serialized steam audio file.

Reverb baking throws warnings unless bakeBatchSize >= 0 default scene bake

There's an inconsistency in the documentation for this. When specifying baking params for reverb, it's not stated anywhere that bakeBatchSize needs to be a non-zero value. Within the documentation this field makes note of Radeon Rays, however, the warning from the baker refers to this as "max sources"

Baking progress callbacks can return NaN

When baking, we can specify a status/progress callback. There are situations where NaN can be passed to our callback function. This can lead to unexpected results when handling how far along the baking process is.

No ability to append probes to a probe array

If you want to place one probe at a time within a probe array, there's no nice way to handle this. The workflow is to use iplProbeArrayGenerateProbes with IPL_PROBEGENERATIONTYPE_CENTROID, then add this to a probe batch. Calling iplProbeArrayGenerateProbes multiple times on a single probe array ends up replacing all the probes within the array. Having an option to append without deleting previous probes would make it more intuitive to use.

Loading a probe batch from serialized data should automatically commit

Loading serialized data overwrites everything within the probe batch already. There's no reason commit shouldn't be called here automatically as it's a major change. It's a bit counter-intuitive and caught me off guard.

There might have been a few other oddities I missed but if they come back to me I'll update the issue

[DenisSulyagin]

it seems that the developer abandoned the project