LabSoundC.hpp

/*
LabSound C
Copyright 2022 Nick Porcino & the LabSound Authors

LabSound C provides a uniform functional interface to the
LabSound library. LabSound itself is written in C++, and has
a highly polymorphic API meant to emulate close the WebAudio
interfaces. That's very handy for transliterating WebAudio code,
but less friendly for native prograaming. This API exposes
all of the functionality of LabSound, but reduces the interface
surface to a few dozen function calls.

Under the hood it maintains a full database of LabSound objects
however in order to avoid the need to expose object life cycles
outside of the implementation, all the objects are tracked using
FLECS, and managed transparently to the user. Since the 
LabSound C interface itself is pass by object, all of the complexity
of object ownership is bypassed since a user of the interface
will never have a copy of anything owned by LabSound.

The only exception is the API object itself, the user is responsible
for its lifetime, and the interface is only usable after the
api object is created, and before it is destroyed.

The WebAudio interface involves a certain amount of set up,
occasionally value setting, and tear down. Other than that, it's
normal to simply let a graph run. As such, the fact that the
LabSound C interface goes through a FLECS hash to find the
backing objects for API application is not particularly of
concern, as it won't be a run time overhead, only a set up
overhead.
 */


// LSNAMESPACE is allows the introduction of a namespace to the symbols so that 
// multiple libraries can include the labsound C library without symbol 
// conflicts. The default is ls_1_0_ to indicate the 1.0 version of LabSound.
//
#ifndef LSNAMESPACE
//#define LSNAMESPACE ls_1_0_
#endif

// The LSCONCAT macro is used to apply a namespace to the symbols in the public
// interface.
#define LSCONCAT1(a, b) a ## b
#define LSCONCAT(a, b) LSCONCAT1(a, b)

// LSAPI may be overridden externally to control symbol visibility.
#ifndef LSAPI
#define LSAPI
#endif

#ifdef __cplusplus
#define LSEXTERNC extern "C" LSAPI
#else
#define LSEXTERNC extern LSAPI
#endif


#ifdef __cplusplus
extern "C" {
#endif

#ifdef LSNAMESPACE
// forward declare the LabSound C types in a namespace
#define ls_StringSlice LSCONCAT(LSNAMESPACE, StringSlice)
#define ls_NameArray LSCONCAT(LSNAMESPACE, NameArray)
#define ls_Seconds LSCONCAT(LSNAMESPACE, Seconds)
#define ls_InputPin LSCONCAT(LSNAMESPACE, InputPin)
#define ls_OutputPin LSCONCAT(LSNAMESPACE, OutputPin)
#define ls_Node LSCONCAT(LSNAMESPACE, Node)
#define ls_Connection LSCONCAT(LSNAMESPACE, Connection)
#define ls_BusData LSCONCAT(LSNAMESPACE, BusData)
#define ls_PinKind LSCONCAT(LSNAMESPACE, PinKind)
#define ls_PinDataType LSCONCAT(LSNAMESPACE, PinDataType)
#endif

typedef struct {
    const char* start;
    const char* end;
} ls_StringSlice;

#define ls_cstr(s) ls_StringSlice { (s), strlen(s) }

typedef struct {
    ls_StringSlice* names;
    int count;
} ls_NameArray;

typedef struct {
    float t;
} ls_Seconds;

typedef struct {
    uint64_t id;
} ls_InputPin;
const ls_InputPin ls_InputPin_empty = { 0 };
typedef struct {
    uint64_t id;
} ls_OutputPin;
const ls_OutputPin ls_OutputPin_empty = { 0 };

typedef struct {
    uint64_t id;
} ls_Node;
const ls_Node ls_Node_empty = { 0 };

typedef struct {
    uint64_t id;
} ls_Connection;
const ls_Connection ls_Connection_empty = { 0 };

typedef struct {
    uint64_t id;
} ls_BusData;
const ls_BusData ls_BusData_empty = { 0 };

typedef enum {
    ls_PinKindInvalid = 0,
    ls_PinKindInput, ls_PinKindOutput, ls_PinKindParam, ls_PinKindSetting
} ls_PinKind;

typedef enum {
    ls_Invalid = 0, 
    ls_String, ls_Path, ls_Bool, ls_Int, ls_Float, ls_Bus, ls_Enum
} ls_PinDataType;

#define ls_APIDetail LSCONCAT(LSNAMESPACE, APIDetail)
struct ls_APIDetail;
#define ls_API LSCONCAT(LSNAMESPACE, API)

LSAPI
struct ls_API {
    struct ls_APIDetail* _detail;

    // operations on nodes
    //
    ls_Seconds (*node_get_timing)(struct ls_API*,
        ls_Node);

    ls_Seconds (*node_get_self_timing)(struct ls_API*,
        ls_Node);

    void (*node_diagnose)(struct ls_API*,
                          ls_Node);
    
    void (*node_start)(struct ls_API*,
        ls_Node, ls_Seconds);

    void (*node_schedule)(struct ls_API*,
        ls_Node, ls_Seconds, int32_t);
    
    const char* (*node_scheduled_state_name)(struct ls_API*,
        ls_Node);

    void (*node_stop)(struct ls_API*,
        ls_Node, ls_Seconds);

    // getting pins from nodes
    //
    ls_InputPin (*node_named_input)(struct ls_API*,
        ls_Node, ls_StringSlice);

    ls_InputPin (*node_indexed_input)(struct ls_API*,
        ls_Node, int);

    ls_OutputPin (*node_named_output)(struct ls_API*,
        ls_Node, ls_StringSlice);

    ls_OutputPin (*node_indexed_output)(struct ls_API*,
        ls_Node, int);

    ls_InputPin (*node_parameter)(struct ls_API*,
        ls_Node, ls_StringSlice);

    ls_InputPin (*node_setting)(struct ls_API*,
        ls_Node, ls_StringSlice);

    void (*node_set_on_ended)(struct ls_API*,
        ls_Node, void(*)());

    ls_PinKind (*pin_kind)(struct ls_API*,
        ls_InputPin);

    ls_PinDataType (*pin_data_type)(struct ls_API*,
        ls_InputPin);

    // managing nodes
    //
    const ls_NameArray* (*node_names)(struct ls_API*);

    ls_Node (*node_create)(struct ls_API*, 
        ls_StringSlice name, ls_StringSlice type);

    void (*node_delete)(struct ls_API*,
        ls_Node);

    void (*create_node_output)(struct ls_API*,
        ls_Node, ls_StringSlice name, int channels);
    
    // setting and getting pin values
    //
    void (*set_float)(struct ls_API*,
        ls_InputPin, float);

    void (*set_enum)(struct ls_API*,
        ls_InputPin, uint32_t);

    void (*set_int)(struct ls_API*,
        ls_InputPin, uint32_t);

    void (*set_bool)(struct ls_API*,
        ls_InputPin, bool);

    void (*set_bus)(struct ls_API*,
        ls_InputPin, ls_BusData);
   
    void (*set_bus_from_file)(struct ls_API*,
        ls_InputPin, ls_StringSlice path);

    void (*set_named_enum)(struct ls_API*,
        ls_InputPin, ls_StringSlice enum_name);

    // managing busses
    ls_BusData (*bus_create_from_file)(struct ls_API*,
        const char* path, bool mix_to_mono);

    // graph management
    //
    ls_Node(*destination_node)(struct ls_API*);

    ls_Connection (*connect)(struct ls_API*,
        ls_InputPin input, ls_OutputPin output);

    // after disconnection, ls_Connection will no longer be valid
    void (*disconnect)(struct ls_API*,
        ls_Connection);
};

typedef struct {
    void* (*malloc)(size_t);
    void (*free)(void*);
} ls_Alloc;
const ls_Alloc ls_default_alloc = { malloc, free };

struct ls_API* ls_create_api_1_0(ls_Alloc);
void ls_release_api_1_0(struct ls_API*);
void ls_idle(struct ls_API*);

typedef struct ls_API LabSoundAPI;