path: root/src/libao.ads

--  Programmed by Jedidiah Barber
--  Released into the public domain


pragma Ada_2012;


with

    Interfaces;

private with

    Ada.Finalization,
    Ada.Containers.Vectors,
    Interfaces.C.Strings,
    System;


package Libao is


    ---------------------------------
    --  Data Types and Structures  --
    ---------------------------------

    type Driver_ID_Number is new Natural;


    type Data_Buffer is new String;


    type Device is tagged private;


    type Info is tagged private;
    type Info_Array is array (Positive range <>) of Info;
    type Output_Kind is (Live_Output, File_Output);
    type Endianness is (Little_Endian, Big_Endian, Machine_Native);

    function Kind
           (Attributes : in Info)
        return Output_Kind;

    function Name
           (Attributes : in Info)
        return String;

    function Short_Name
           (Attributes : in Info)
        return String;

    function Preferred_Byte_Format
           (Attributes : in Info)
        return Endianness;

    function Priority_Level
           (Attributes : in Info)
        return Positive;

    function Comment
           (Attributes : in Info)
        return String;

    function Option_Count
           (Attributes : in Info)
        return Natural;

    function Option_Key
           (Attributes : in Info;
            Index      : in Positive)
        return String;


    type Option_List is tagged private;

    Empty_Options : constant Option_List;


    type Sample_Format is tagged private;
    type Channel_Mnemonic is (L, R, C, M, CL, CR, BL, BR, BC, SL, SR, LFE, A1, A2, A3, A4, X);
    type Mnemonic_Array is array (Positive range <>) of Channel_Mnemonic;

    function Create
           (Bits, Rate, Channels : in Positive;
            Byte_Format          : in Endianness;
            Channel_Matrix       : in Mnemonic_Array)
        return Sample_Format;

    Stereo       : constant Mnemonic_Array := (L, R);
    Quadraphonic : constant Mnemonic_Array := (L, R, BL, BR);




    ------------------
    --  Exceptions  --
    ------------------

    --  May be raised by Open_Live, Open_File, Driver_ID, Driver_Info
    No_Driver_Error : exception;

    --  May be raised by Open_File
    Not_File_Error : exception;

    --  May be raised by Open_Live
    Not_Live_Error : exception;

    --  May be raised by Open_Live, Open_File
    Bad_Option_Error : exception;

    --  May be raised by Open_Live
    Open_Device_Error : exception;

    --  May be raised by Shutdown, Close
    Close_Device_Error : exception;

    --  May be raised by Default_Driver_ID
    No_Device_Error : exception;

    --  May be raised by Open_File
    Open_File_Error : exception;

    --  May be raised by Open_File
    File_Exists_Error : exception;

    --  Documentation lacking, but presumably may be raised by Open_Live, Open_File
    Bad_Format_Error : exception;

    --  May be raised by Open_Live, Open_File, Play
    General_Failure : exception;

    --  Storage_Error may be raised by Append, Append_Global_Option
    --  Program_Error may be raised if libao in general does something out of spec




    --------------------------------------
    --  Device Setup/Playback/Teardown  --
    --------------------------------------

    procedure Append
           (This  : in out Option_List;
            Key   : in     String;
            Value : in     String);

    procedure Append_Global_Option
           (Key   : in String;
            Value : in String);

    procedure Open_Live
           (Output    : in out Device;
            Driver_ID : in     Driver_ID_Number;
            Format    : in     Sample_Format'Class;
            Options   : in     Option_List'Class);

    procedure Open_File
           (Output    : in out Device;
            Driver_ID : in     Driver_ID_Number;
            Filename  : in     String;
            Format    : in     Sample_Format'Class;
            Options   : in     Option_List'Class;
            Overwrite : in     Boolean := False);

    procedure Play
           (Output  : in Device;
            Samples : in Data_Buffer);

    procedure Close
           (Output : in out Device);




    --------------------------
    --  Driver Information  --
    --------------------------

    function Driver_ID
           (Short_Name : in String)
        return Driver_ID_Number;

    function Default_Driver_ID
        return Driver_ID_Number;

    function Driver_Info
           (Ident : in Driver_ID_Number)
        return Info;

    function Driver_Info_List
        return Info_Array;

    function File_Extension
           (Ident : in Driver_ID_Number)
        return String;




    ---------------------
    --  Miscellaneous  --
    ---------------------

    function Is_Big_Endian
        return Boolean;


private


    pragma Linker_Options ("-lao");


    procedure Do_Append
           (Ptr   : in out System.Address;
            Key   : in     Interfaces.C.char_array;
            Value : in     Interfaces.C.char_array);

    procedure Do_Close
           (Ptr : in System.Address);


    type Device is tagged record
        Ptr : System.Address := System.Null_Address;
    end record;


    type Info is tagged record
        Ptr : System.Address := System.Null_Address;
    end record;


    type Option_List is new Ada.Finalization.Controlled with record
        Ptr : System.Address := System.Null_Address;
    end record;

    overriding procedure Adjust
           (This : in out Option_List);

    overriding procedure Finalize
           (This : in out Option_List);

    Empty_Options : constant Option_List :=
        (Ada.Finalization.Controlled with Ptr => System.Null_Address);


    type C_Sample_Format is record
        Bits        : Interfaces.C.int;
        Rate        : Interfaces.C.int;
        Channels    : Interfaces.C.int;
        Byte_Format : Interfaces.C.int;
        Matrix      : Interfaces.C.Strings.chars_ptr;
    end record with Convention => C;

    type Sample_Format is new Ada.Finalization.Controlled with record
        C_Struct : C_Sample_Format;
    end record;

    overriding procedure Adjust
           (This : in out Sample_Format);

    overriding procedure Finalize
           (This : in out Sample_Format);


    --  Keep track of open devices
    package Address_Vectors is new Ada.Containers.Vectors
       (Index_Type   => Positive,
        Element_Type => System.Address,
        "="          => System."=");

    Device_List : Address_Vectors.Vector := Address_Vectors.Empty_Vector;


    --  The clunky way of ensuring that libao is always shut down properly
    type Final_Controller is new Ada.Finalization.Controlled with null record;

    overriding procedure Finalize
           (This : in out Final_Controller);

    Cleanup : Final_Controller;


end Libao;