Subject: [linux-audio-dev] LAAGA proposal, part ??
From: Paul Davis (pbd_AT_Op.Net)
Date: Wed Jun 06 2001 - 19:08:16 EEST
First, an example
-----------------
/*
This creates a very simple audio application that accepts a mono
input audio data stream and copies it to a single mono output audio
data stream. This is actually an inefficient way to do this, but it
will illustrate the basic idea of the API.
*/
#include <stdio.h>
#include <audioengine.h>
audioengine_port_t *my_input_port;
audioengine_port_t *my_output_port;
int
process (nframes_t nframes)
{
audioengine_sample_t *in, *out;
in = audioengine_port_get_buffer (my_input_port);
out = audioengine_port_get_buffer (my_output_port);
while (--nframes) {
*out++ = *in++;
}
return 0;
}
int
bufsize (nframes_t nframes)
{
printf ("the maximum buffer size is now %u\n", nframes);
return 0;
}
int
srate (nframes_t nframes)
{
printf ("the sample rate is now %u/sec\n", nframes);
return 0;
}
main ()
{
audioengine_open ("myname", process, bufsize, srate);
printf ("connected to the audioengine, sample rate = %u, maximum buffer size = %u\n",
audioengine_get_sample_rate(),
audioengine_get_buffer_size ());
my_input_port = audioengine_port_register
("input", AUDIOENGINE_DEFAULT_AUDIO_TYPE, PortIsInput);
my_output_port = audioengine_port_register
("output", AUDIOENGINE_DEFAULT_AUDIO_TYPE, PortIsOutput);
/* create gui */
/* run gui */
}
************************************************************************
The client API
--------------
/* a client calls this function to initiate use of the audioengine.
The callback arguments will be called as follows:
process: whenever the audioengine decides that audio data
is available, this callback will be executed
with the number of frames of audio data to be
generated/captured passed as its argument.
buffer_size: called whenever the audioengine decides
to change the maximum size of the argument
that could be passed to the process callback.
this will be called once during the execution
of audioengine_open().
sample_rate: called whenever the audioengine changes the
sample rate of the output device. this will
be called once during the execution of
audioengine_open().
the buffer size and sample rate callbacks are guaranteed
to be called synchronously and single-threaded with
respect to the calling of the "process" callback. that is,
the code executed by these callbacks need not meet RT
constraints, and it does need to use synchronization primitives
to avoid problems with the process callback.
*/
int
audioengine_open (const char *client_name,
int (*process_callback)(nframes_t),
int (*buffer_size_callback)(nframes_t),
int (*sample_rate_callback)(nframes_t));
/* this creates a new port for the client.
a port is an object used for moving data in or out of the client.
the data may be of any type. ports may be connected to each other
in various ways.
a port has a short name, which may be any non-NULL and non-zero
length string, and is passed as the first argument. a port's full
name is the name of the client concatenated with a colon (:) and
then its short name.
a port has a type, which may be any non-NULL and non-zero length string,
and is passed as the second argument. for types that are not built
into the audioengine API (currently just "32 bit floating point
audio"), the client MUST supply a pointer to a pointer to a region
of memory to be used for the data associated with the port. this is
passed as the fourth argument. for builtin types, the fourth
argument should always be NULL.
a port has a set of flags, enumerated below and passed as the third
argument in the form of a bitmask created by AND-ing together the
desired flags. the flags "IsInput" and "IsOutput" are mutually
exclusive and it is an error to use them both.
*/
enum PortFlags {
PortIsInput = 0x1,
PortIsOutput = 0x2,
PortIsMulti = 0x4, /* supports multiple connections */
PortIsPhysical = 0x8 /* refers to a physical connection */
};
audioengine_port_t *
audioengine_port_register (const char *port_name,
const char *port_type,
unsigned long flags,
void *buffer);
/* this removes the port from the client */
int
audioengine_port_unregister (audioengine_port_t *);
/* this returns a pointer to the memory area associated
with the port. it should only be called from within
the "process" callback. the memory area can be
written to directly using simple memory assignment
semantics:
some_type_t *t = (some_type_t *) audioengine_port_get_buffer (port);
while (some condition) {
*t++ = some value;
}
*/
void *audioengine_port_get_buffer (audioengine_port_t *);
/* these two functions establish and disestablish a connection
between two ports. when a connection exists, data written
to the source port will be available to be read at the destination
port.
the types of both ports must be identical to establish a connection.
the flags of the source port must include PortIsOutput.
the flags of the destination port must include PortIsInput.
*/
int audioengine_port_connect (const char *source_port,
const char *destination_port);
int audioengine_port_disconnect (const char *source_port,
const char *destination_port);
/* a client may call this function to prevent other objects
from changing the connection status of the named port.
*/
int audioengine_port_lock (const char *port_name);
/* this returns the sample rate of the audioengine */
unsigned long audioengine_get_sample_rate ();
/* this returns the current maximum size that will
ever be passed to the "process" callback.
*/
unsigned long audioengine_get_buffer_size ();
/* This function returns a list of ports that match the specified
arguments.
port_name_pattern: a regular expression used to select ports by name.
if NULL or of zero length, no selection based on
name will be carried out.
type_name_pattern: a regular expression used to select ports by type.
if NULL or of zero length, no selection based on
type will be carried out.
flags: a value used to select ports by their flags. if
zero, no selection based on flags will be carried out.
*/
some_list_type_t *audioengine_get_ports (const char *port_name_pattern,
const char *type_name_pattern,
unsigned long flags);
This archive was generated by hypermail 2b28 : Wed Jun 06 2001 - 20:17:57 EEST