nt-lite/code/public/ntlite/audio.h

// Public native render-stream syscall ABI declarations.

#pragma once

#include <stdint.h>
#include <stdbool.h>
#include <ntlite/status.h>
#include <ntlite/handle.h>

#define SYS_AUDIO_ABI_VERSION 5u
#define SYS_AUDIO_MAX_ENDPOINTS 32u
#define SYS_AUDIO_STREAM_CAPACITY_FRAMES 4096u

#define SYS_AUDIO_GAIN_Q16_UNITY 65536u
#define SYS_AUDIO_PAN_Q16_LEFT (-65536)
#define SYS_AUDIO_PAN_Q16_CENTER 0
#define SYS_AUDIO_PAN_Q16_RIGHT 65536

// Identifies one logical render destination.
typedef enum SYS_AUDIO_ENDPOINT_KIND {
    SysAudioEndpointLineOut = 1,
    SysAudioEndpointSpeakerHeadphone,
    SysAudioEndpointOtherAnalog
} SYS_AUDIO_ENDPOINT_KIND;

// Identifies the interleaved PCM sample representation accepted by native streams.
typedef enum SYS_AUDIO_SAMPLE_FORMAT {
    SysAudioSampleS16 = 1
} SYS_AUDIO_SAMPLE_FORMAT;

// Describes one interleaved PCM stream format.
typedef struct SYS_AUDIO_FORMAT {
    uint32_t SampleRate;
    uint16_t ChannelCount;
    uint16_t SampleFormat;
} SYS_AUDIO_FORMAT;

#define SYS_AUDIO_ENDPOINT_FLAG_AVAILABLE 0x00000001u
#define SYS_AUDIO_ENDPOINT_FLAG_DEFAULT   0x00000002u
#define SYS_AUDIO_ENDPOINT_FLAG_VALID_MASK 0x00000003u

#define SYS_AUDIO_ENDPOINT_CAP_JACK_SENSE    0x00000001u
#define SYS_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN 0x00000002u
#define SYS_AUDIO_ENDPOINT_CAP_VALID_MASK    0x00000003u

// Identifies the lifecycle state reported for one render endpoint.
typedef enum SYS_AUDIO_ENDPOINT_STATE {
    SysAudioEndpointStarting = 1,
    SysAudioEndpointReady,
    SysAudioEndpointStopping,
    SysAudioEndpointFailed,
    SysAudioEndpointRemoved
} SYS_AUDIO_ENDPOINT_STATE;

// Reports one endpoint snapshot keyed by its stable kernel identifier.
typedef struct SYS_AUDIO_ENDPOINT_INFO {
    uint32_t Size;
    uint32_t Version;
    uint32_t EndpointId;
    uint32_t Kind;
    uint32_t Flags;
    uint32_t Capabilities;
    uint32_t State;
    SYS_AUDIO_FORMAT HardwareFormat;
    uint32_t PeriodCount;
    uint32_t FramesPerPeriod;
    uint32_t MasterVolumeQ16;
    bool MasterMuted;
    KSTATUS FailureStatus;
    uint32_t Reserved;
} SYS_AUDIO_ENDPOINT_INFO;

// Selects the endpoint array used by one enumeration call.
typedef struct SYS_AUDIO_ENUMERATE_ENDPOINTS_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    SYS_AUDIO_ENDPOINT_INFO* Endpoints;
    uint32_t Capacity;
    uint32_t Reserved;
    uint32_t* CountOut;
} SYS_AUDIO_ENUMERATE_ENDPOINTS_REQUEST;

// Selects one endpoint and source format for a new render stream handle.
typedef struct SYS_AUDIO_OPEN_STREAM_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    uint32_t EndpointId;
    SYS_AUDIO_FORMAT Format;
    uint32_t Reserved;
    SYS_HANDLE* StreamHandleOut;
} SYS_AUDIO_OPEN_STREAM_REQUEST;

// Describes one bounded nonblocking stream write.
typedef struct SYS_AUDIO_WRITE_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    SYS_HANDLE StreamHandle;
    uint32_t FrameCount;
    const void* Frames;
    uint32_t* WrittenFramesOut;
} SYS_AUDIO_WRITE_REQUEST;

#define SYS_AUDIO_WAIT_WRITABLE      0x00000001u
#define SYS_AUDIO_WAIT_CONSUMED      0x00000002u
#define SYS_AUDIO_WAIT_PRESENTED     0x00000004u
#define SYS_AUDIO_WAIT_STOPPED       0x00000008u
#define SYS_AUDIO_WAIT_DRAINED       0x00000010u
#define SYS_AUDIO_WAIT_FAILED        0x00000020u
#define SYS_AUDIO_WAIT_DISCONTINUITY 0x00000040u
#define SYS_AUDIO_WAIT_VALID_MASK    0x0000007Fu

// Arms the stream handle event for one or more progress conditions.
typedef struct SYS_AUDIO_ARM_WAIT_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    SYS_HANDLE StreamHandle;
    uint32_t Mask;
    // Frame counters are inclusive absolute targets and generations are change baselines.
    uint32_t WritableFrames;
    uint32_t Reserved;
    uint64_t ConsumedFrames;
    uint64_t PresentedFrames;
    uint64_t DrainedGeneration;
    uint64_t DiscontinuityGeneration;
} SYS_AUDIO_ARM_WAIT_REQUEST;

// Identifies the public lifecycle state of one native render stream.
typedef enum SYS_AUDIO_STREAM_STATE {
    SysAudioStreamCreated = 1,
    SysAudioStreamRunning,
    SysAudioStreamPaused,
    SysAudioStreamDraining,
    SysAudioStreamStopped,
    SysAudioStreamFailed
} SYS_AUDIO_STREAM_STATE;

// Reports one coherent stream snapshot.
typedef struct SYS_AUDIO_STREAM_INFO {
    uint32_t Size;
    uint32_t Version;
    uint32_t State;
    uint32_t Reserved;
    SYS_AUDIO_FORMAT Format;
    uint32_t CapacityFrames;
    uint32_t BufferedFrames;
    uint32_t WritableFrames;
    KSTATUS FailureStatus;
    uint64_t FramesSubmitted;
    uint64_t FramesConsumed;
    uint64_t FramesPresented;
    uint64_t FramesDiscarded;
    uint64_t OutputFramesMixed;
    uint64_t SilenceFramesInserted;
    // Underruns count recoverable source starvation periods.
    uint64_t Underruns;
    uint64_t DrainedGeneration;
    // Discontinuities report explicit control or hardware timeline changes.
    uint64_t DiscontinuityGeneration;
    uint32_t VolumeQ16;
    int32_t PanQ16;
    bool Muted;
    uint8_t ReservedBytes[7];
} SYS_AUDIO_STREAM_INFO;

// Updates one stream's software gain, balance, and mute targets.
// Volume uses unsigned Q16 in [0, 1] and pan uses signed Q16 in [-1, 1].
typedef struct SYS_AUDIO_SET_VOLUME_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    SYS_HANDLE StreamHandle;
    bool Muted;
    uint32_t VolumeQ16;
    int32_t PanQ16;
} SYS_AUDIO_SET_VOLUME_REQUEST;

// Updates one endpoint's master software gain and mute state.
typedef struct SYS_AUDIO_SET_MASTER_VOLUME_REQUEST {
    uint32_t Size;
    uint32_t Flags;
    uint32_t EndpointId;
    bool Muted;
    uint32_t VolumeQ16;
} SYS_AUDIO_SET_MASTER_VOLUME_REQUEST;

// Enumerates render endpoints and returns the complete count even when capacity is insufficient.
KSTATUS SysAudioEnumerateEndpoints(const SYS_AUDIO_ENUMERATE_ENDPOINTS_REQUEST* request);

// Opens one waitable, process-owned native render stream handle.
KSTATUS SysAudioOpenStream(const SYS_AUDIO_OPEN_STREAM_REQUEST* request);

// Copies as many complete frames as currently fit and returns WOULD_BLOCK when none fit.
KSTATUS SysAudioWrite(const SYS_AUDIO_WRITE_REQUEST* request);

// Replaces the any-condition progress targets that drive one stream handle's wait state.
KSTATUS SysAudioArmWait(const SYS_AUDIO_ARM_WAIT_REQUEST* request);

// Copies one coherent stream snapshot after the caller initializes infoOut->Size.
KSTATUS SysAudioQueryStream(SYS_HANDLE streamHandle, SYS_AUDIO_STREAM_INFO* infoOut);

// Starts one created or stopped stream.
KSTATUS SysAudioStart(SYS_HANDLE streamHandle);

// Pauses future mixing while preserving unconsumed source frames.
KSTATUS SysAudioPause(SYS_HANDLE streamHandle);

// Resumes one paused stream.
KSTATUS SysAudioResume(SYS_HANDLE streamHandle);

// Rejects new writes and stops after all submitted frames reach a terminal disposition.
KSTATUS SysAudioDrain(SYS_HANDLE streamHandle);

// Stops future mixing and discards source frames not yet committed to hardware periods.
KSTATUS SysAudioStop(SYS_HANDLE streamHandle);

// Returns one stopped stream to an empty position-zero state.
KSTATUS SysAudioReset(SYS_HANDLE streamHandle);

// Updates one stream's software volume, pan, and mute state.
KSTATUS SysAudioSetVolume(const SYS_AUDIO_SET_VOLUME_REQUEST* request);

// Updates one endpoint's master software volume and mute state.
KSTATUS SysAudioSetMasterVolume(const SYS_AUDIO_SET_MASTER_VOLUME_REQUEST* request);