C API reference

SofaMyRoom is a C library, libroomsim, with three front ends: the sofamyroom command line tool, the MATLAB MEX file and the Python package. Two headers are meant for other programs; the reference below is extracted from their comments.

src/libroomsim/include/capi.h is the embedding interface: a handful of plain C functions that take the setup as text and return the impulse responses, without exposing the internal structures. It is what pysofamyroom calls through ctypes and it is exported from the shared library built with -DSOFAMYROOM_PYTHON=ON.

src/libroomsim.h is the original Roomsim interface used by main.c and mexmain.c; it works on the parsed setup structure (CRoomSetup in src/libroomsim/include/types.h, filled by ReadSetup() and LoadCRoomSetup()) and is the one to use when linking the static library directly.

All functions must be called from one thread at a time: the simulator keeps global state (the cache of loaded sensors and the error slot).

Embedding interface (capi.h)

Plain C entry points for embedding SofaMyRoom (used by pysofamyroom).

struct smr_brir

One source/receiver impulse response. Samples are stored channel by channel: sample[j + n_samples*k] is sample j of channel k.

double fs

Sampling frequency in Hz (options.fs of the setup).

int n_samples

Number of samples per channel.

int n_channels

Number of channels (two for a SOFA receiver).

const double *sample

n_samples*n_channels doubles, owned by the result.

struct smr_result

Result of one simulation: n_sources*n_receivers responses, where brir[r*n_sources + s] belongs to source s and receiver r (same order as the MATLAB cell array and the CLI output files).

int n_sources

Number of sources in the setup.

int n_receivers

Number of receivers in the setup.

smr_brir *brir

The n_sources*n_receivers responses.

void *handle

Internal, do not touch.

typedef void (*smr_log_fn)(const char *text)

Callback receiving the status messages printed by the simulator.

const char *smr_version(void)

Library version string (SOFAMYROOM_VERSION).

int smr_simulate_text(const char *text, size_t length, smr_result **out)

Run a simulation from the text of a setup file (same grammar as the CLI). Returns 0 and sets *out on success, a negative value on failure; smr_last_error() then holds the message.

int smr_simulate_file(const char *path, smr_result **out)

Same as smr_simulate_text(), reading the setup from a file.

void smr_result_free(smr_result *result)

Release a result returned by smr_simulate_text() or smr_simulate_file(); NULL is allowed.

const char *smr_last_error(void)

Message of the last failed call, empty string if none.

void smr_clear_sensors(void)

Drop the cached sources/receivers (SOFA files) kept between calls.

void smr_set_log(smr_log_fn fn)

Route status messages to fn; NULL restores stdout.

Example

#include <stdio.h>
#include "capi.h"

int main(void)
{
    smr_result *result;
    if (smr_simulate_file("data/sampleroomsetup.txt", &result) < 0) {
        fprintf(stderr, "%s\n", smr_last_error());
        return 1;
    }
    printf("%d responses of %d samples at %.0f Hz\n",
           result->n_sources * result->n_receivers,
           result->brir[0].n_samples, result->brir[0].fs);
    smr_result_free(result);
    smr_clear_sensors();
    return 0;
}

Roomsim interface (libroomsim.h)

Room simulation function prototypes.

void ValidateSetup(const CRoomSetup *pSetup)

Check the ranges and sizes of the setup (six surfaces, one column per frequency band, absorption and diffusion in [0,1], …). An invalid setup stops the program with the message invalid setup: ...; in the embedded library the message is returned by smr_last_error() instead.

BRIR *Roomsim(const CRoomSetup *pSetup)

Run the simulation and return an array of nSources*nReceivers responses, indexed r*nSources + s for source s and receiver r, followed by a terminating element whose sample pointer is NULL.

void ReleaseBRIR(BRIR *brir)

Free an array returned by Roomsim().

void ClearAllSensors(void)

Free the sources and receivers loaded so far (SOFA files are kept in memory between simulations).