From c36d37880986f734a69086b28ac6f0e9df7babab Mon Sep 17 00:00:00 2001 From: Jedidiah Barber Date: Tue, 18 Jul 2023 00:05:43 +1200 Subject: Removed need for initialize/shutdown, improved documentation slightly --- example/aao_example.adb | 8 +--- readme.txt | 20 +++++++--- src/libao.adb | 70 +++++++++++++++++--------------- src/libao.ads | 103 ++++++++++++++++-------------------------------- 4 files changed, 87 insertions(+), 114 deletions(-) diff --git a/example/aao_example.adb b/example/aao_example.adb index 7d12b56..fd32e38 100644 --- a/example/aao_example.adb +++ b/example/aao_example.adb @@ -27,12 +27,9 @@ procedure AAO_Example is begin - -- Initialize TIO.Put_Line ("libao example program"); - Libao.Startup; - -- Setup for default driver @@ -89,12 +86,11 @@ begin -- Close and shutdown - -- Technically the binding will take care of closing open devices at shutdown, - -- but it is always good practice to close them anyway. + -- Technically the binding will take care of closing open devices at the + -- end of runtime, but it is always good practice to close them anyway. Libao.Close (My_Device); - Libao.Shutdown; end AAO_Example; diff --git a/readme.txt b/readme.txt index a0a3233..8cb62c2 100644 --- a/readme.txt +++ b/readme.txt @@ -8,15 +8,21 @@ Overview -------- This a thick binding, so the rough edges of C have all been filed off. In -particular ao_option/Option_List objects are automatically deallocated when -they go out of scope, and any remaining open ao_device/Device objects are -automatically closed when libao is shut down. +particular: + + * ao_initialize/ao_shutdown are now automatic + * ao_option/Option_List objects are deallocated when they go out of scope + * ao_device/Device objects are automatically closed upon program end + * All error codes have been converted to exceptions + +A short example program is available in /example/. Dependencies ------------ -GNAT (build) +An Ada 2012 compiler and standard library (build) +A C compiler and standard library (build) gprbuild (build) libao (run) @@ -38,7 +44,7 @@ programs provided. Further Information ------------------- -API of libao: +C API of libao: https://xiph.org/ao/doc/libao-api.html @@ -49,6 +55,8 @@ This binding and the short Ada example were written by Jedidiah Barber. The short C example program was written by Stan Seibert. -All code is released into the public domain. +All code of this binding and example programs is released into the public +domain. Consult unlicense.txt and the header of the C example program for +further information. diff --git a/src/libao.adb b/src/libao.adb index c1491c2..e10582d 100644 --- a/src/libao.adb +++ b/src/libao.adb @@ -19,6 +19,10 @@ use type package body Libao is + ------------------------ + -- Functions From C -- + ------------------------ + procedure ao_initialize; pragma Import (C, ao_initialize, "ao_initialize"); pragma Inline (ao_initialize); @@ -28,8 +32,6 @@ package body Libao is pragma Inline (ao_shutdown); - - function ao_append_option (Options : in out System.Address; Key : in Interfaces.C.char_array; @@ -83,8 +85,6 @@ package body Libao is pragma Inline (ao_close); - - function ao_driver_id (Short_Name : in Interfaces.C.char_array) return Interfaces.C.int; @@ -115,8 +115,6 @@ package body Libao is pragma Inline (ao_file_extension); - - function ao_is_big_endian return Interfaces.C.int; pragma Import (C, ao_is_big_endian, "ao_is_big_endian"); @@ -295,6 +293,10 @@ package body Libao is + ----------------------------------- + -- Controlled Type Subprograms -- + ----------------------------------- + procedure Adjust (This : in out Option_List) is @@ -329,9 +331,22 @@ package body Libao is Interfaces.C.Strings.Free (This.C_Struct.Matrix); end Finalize; + procedure Finalize + (This : in out Final_Controller) is + begin + for Addy of Device_List loop + Do_Close (Addy); + end loop; + ao_shutdown; + end Finalize; + + --------------------------------- + -- Data Types and Structures -- + --------------------------------- + function Kind (Attributes : in Info) return Output_Kind @@ -409,8 +424,6 @@ package body Libao is end Option_Key; - - function Image_Length (Channel : in Channel_Mnemonic) return Positive is @@ -477,30 +490,9 @@ package body Libao is - function Is_Alive - return Boolean is - begin - return Alive_Status; - end Is_Alive; - - procedure Startup is - begin - ao_initialize; - Device_List.Clear; - Alive_Status := True; - end Startup; - - procedure Shutdown is - begin - for Addy of Device_List loop - Do_Close (Addy); - end loop; - ao_shutdown; - Alive_Status := False; - end Shutdown; - - - + -------------------------------------- + -- Device Setup/Playback/Teardown -- + -------------------------------------- procedure Do_Append (Ptr : in out System.Address; @@ -657,6 +649,10 @@ package body Libao is + -------------------------- + -- Driver Information -- + -------------------------- + function Driver_ID (Short_Name : in String) return Driver_ID_Number @@ -730,6 +726,10 @@ package body Libao is + --------------------- + -- Miscellaneous -- + --------------------- + function Is_Big_Endian return Boolean is begin @@ -741,6 +741,12 @@ package body Libao is end Is_Big_Endian; + + +begin + + ao_initialize; + end Libao; diff --git a/src/libao.ads b/src/libao.ads index 1bdb142..9e1cde1 100644 --- a/src/libao.ads +++ b/src/libao.ads @@ -15,9 +15,9 @@ private with package Libao is - ----------------------- - -- Data Structures -- - ----------------------- + --------------------------------- + -- Data Types and Structures -- + --------------------------------- type Driver_ID_Number is new Natural; @@ -35,44 +35,36 @@ package Libao is function Kind (Attributes : in Info) - return Output_Kind - with Pre => Is_Alive; + return Output_Kind; function Name (Attributes : in Info) - return String - with Pre => Is_Alive; + return String; function Short_Name (Attributes : in Info) - return String - with Pre => Is_Alive; + return String; function Preferred_Byte_Format (Attributes : in Info) - return Endianness - with Pre => Is_Alive; + return Endianness; function Priority_Level (Attributes : in Info) - return Positive - with Pre => Is_Alive; + return Positive; function Comment (Attributes : in Info) - return String - with Pre => Is_Alive; + return String; function Option_Count (Attributes : in Info) - return Natural - with Pre => Is_Alive; + return Natural; function Option_Key (Attributes : in Info; Index : in Positive) - return String - with Pre => Is_Alive; + return String; type Option_List is tagged private; @@ -139,24 +131,6 @@ package Libao is - ------------------------------ - -- Library Setup/Teardown -- - ------------------------------ - - function Is_Alive - return Boolean; - - procedure Startup - with Pre => not Is_Alive, - Post => Is_Alive; - - procedure Shutdown - with Pre => Is_Alive, - Post => not Is_Alive; - - - - -------------------------------------- -- Device Setup/Playback/Teardown -- -------------------------------------- @@ -164,20 +138,17 @@ package Libao is procedure Append (This : in out Option_List; Key : in String; - Value : in String) - with Pre => Is_Alive; + Value : in String); procedure Append_Global_Option (Key : in String; - Value : in String) - with Pre => Is_Alive; + Value : in String); function Open_Live (Driver_ID : in Driver_ID_Number; Format : in Sample_Format; Options : in Option_List'Class) - return Device - with Pre => Is_Alive; + return Device; function Open_File (Driver_ID : in Driver_ID_Number; @@ -185,17 +156,14 @@ package Libao is Format : in Sample_Format; Options : in Option_List'Class; Overwrite : in Boolean := False) - return Device - with Pre => Is_Alive; + return Device; procedure Play (Output_Device : in Device; - Samples : in Data_Buffer) - with Pre => Is_Alive; + Samples : in Data_Buffer); procedure Close - (Output_Device : in out Device) - with Pre => Is_Alive; + (Output_Device : in out Device); @@ -206,26 +174,21 @@ package Libao is function Driver_ID (Short_Name : in String) - return Driver_ID_Number - with Pre => Is_Alive; + return Driver_ID_Number; function Default_Driver_ID - return Driver_ID_Number - with Pre => Is_Alive; + return Driver_ID_Number; function Driver_Info (Ident : in Driver_ID_Number) - return Info - with Pre => Is_Alive; + return Info; function Driver_Info_List - return Info_Array - with Pre => Is_Alive; + return Info_Array; function File_Extension (Ident : in Driver_ID_Number) - return String - with Pre => Is_Alive; + return String; @@ -235,17 +198,13 @@ package Libao is --------------------- function Is_Big_Endian - return Boolean - with Pre => Is_Alive; + return Boolean; private pragma Linker_Options ("-lao"); - pragma Inline (Is_Alive); - - procedure Do_Append @@ -257,8 +216,6 @@ private (Ptr : in System.Address); - - type Device is record Ptr : System.Address; end record; @@ -302,10 +259,7 @@ private (This : in out Sample_Format); - - - Alive_Status : Boolean := False; - + -- Keep track of package Address_Vectors is new Ada.Containers.Vectors (Index_Type => Positive, Element_Type => System.Address, @@ -314,6 +268,15 @@ private 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; -- cgit