carb/audio/IAudioGroup.h

File members: carb/audio/IAudioGroup.h

// Copyright (c) 2019-2023, NVIDIA CORPORATION. All rights reserved.
//
// NVIDIA CORPORATION and its licensors retain all intellectual property
// and proprietary rights in and to this software, related documentation
// and any modifications thereto. Any use, reproduction, disclosure or
// distribution of this software and related documentation without an express
// license agreement from NVIDIA CORPORATION is strictly prohibited.
//
#pragma once

#include "../Interface.h"
#include "AudioTypes.h"
#include "IAudioData.h"
#include "IAudioPlayback.h"

namespace carb
{
namespace audio
{

/************************************* Interface Objects *****************************************/
struct Group;

/******************************** typedefs, enums, & macros **************************************/
typedef uint32_t GroupFlags;

constexpr GroupFlags fGroupFlagFixedSeed = 0x00000001;

struct SoundEntry
{
    SoundData* sound;

    uint64_t playStart = 0;

    uint64_t playLength = 0;

    UnitType playUnits = UnitType::eFrames;
};

struct GroupDesc
{
    GroupFlags flags = 0;

    const char* name = nullptr;

    size_t count = 0;

    SoundEntry* initialSounds = nullptr;

    void* ext = nullptr;
};

enum class ChooseType
{
    eRandom,

    eNext,

    ePrevious,

    eFirst,

    eLast,
};

constexpr size_t kGroupIndexAll = ~0ull;

constexpr size_t kGroupIndexInvalid = static_cast<size_t>(-2);

struct ProbabilityDesc
{
    size_t index;

    float probability;

    void* ext = nullptr;
};

/******************************** Audio Sound Group Management Interface *******************************/
struct IAudioGroup
{
    CARB_PLUGIN_INTERFACE("carb::audio::IAudioGroup", 1, 0)

    Group*(CARB_ABI* createGroup)(const GroupDesc* desc);

    void(CARB_ABI* destroyGroup)(Group* group);

    size_t(CARB_ABI* getSize)(const Group* group);

    const char*(CARB_ABI* getName)(const Group* group);

    void(CARB_ABI* setName)(Group* group, const char* name);

    size_t(CARB_ABI* addSound)(Group* group, SoundData* sound);

    size_t(CARB_ABI* addSoundWithRegion)(Group* group, const SoundEntry* sound);

    bool(CARB_ABI* removeSound)(Group* group, SoundData* sound);

    bool(CARB_ABI* removeSoundAtIndex)(Group* group, size_t index);

    bool(CARB_ABI* setSoundRegion)(Group* group, size_t index, const SoundEntry* region);

    SoundData*(CARB_ABI* getSound)(const Group* group, size_t index);

    bool(CARB_ABI* getSoundEntry)(const Group* group, size_t index, SoundEntry* entry);

    void(CARB_ABI* setProbability)(Group* group, const ProbabilityDesc* desc);

    float(CARB_ABI* getProbability)(const Group* group, size_t index);

    float(CARB_ABI* getProbabilityTotal)(const Group* group);

    bool(CARB_ABI* chooseSound)(Group* group, ChooseType type, PlaySoundDesc* play);

    uint32_t(CARB_ABI* getMaxInstances)(const Group* group);

    void(CARB_ABI* setMaxInstances)(Group* group, uint32_t limit);

    void*(CARB_ABI* getUserData)(const Group* group);

    void(CARB_ABI* setUserData)(Group* group, const UserData* userData);
};

} // namespace audio
} // namespace carb