Example of use for an application:
/* Open needed boxes */
soundbox_open
/* Let's know some details */
soundbox_query_property
soundbox_get_property
/* Set box working details */
soundbox_set_property
/* Get port handles */
soundbox_get_port
/* Let's know some details about port */
soundbox_port_query_property
soundbox_port_get_property
/* Set port working details */
soundbox_port_set_property
/* Open wanted flows */
soundbox_flow_open
/* Prepare boxes for work */
soundbox_prepare
while(!end) {
for each input {
soundbox_flow_wait
soundbox_flow_begin
}
for each output {
soundbox_flow_wait
soundbox_flow_begin
}
/* I assume that elaboration transfer directly data from
inputs to outputs */
elaborate
for each input
soundbox_flow_commit(output, ...)
for each output
soundbox_flow_commit(output, ...)
}
/* Close boxes */
soundbox_close
--
Abramo Bagnara mailto:[EMAIL PROTECTED]
Opera Unica Phone: +39.546.656023
Via Emilia Interna, 140
48014 Castel Bolognese (RA) - Italy
ALSA project http://www.alsa-project.org
It sounds good!
/*
* All-in-one sound boxes external API
* Copyright (c) 2001 by Abramo Bagnara <[EMAIL PROTECTED]>
*
*
* This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Library General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*
*/
/************/
/* SOUNDBOX */
/************/
/* Create a soundbox instance from its name and its soundbox dependant args */
int soundbox_open(soundbox_t **soundbox,
soundbox_id_t id, soundbox_args_t *args);
/* Destroy a soundbox instance */
int soundbox_close(soundbox_t *soundbox);
/* Prepare a soundbox for work (allocate needed stuff, create subprocesses, etc.) */
int soundbox_prepare(soundbox_t *soundbox);
/* Bring soundbox to a state where properties change is harmless.
This may deallocate stuff, destroy subprocesses, etc. */
int soundbox_relax(soundbox_t *soundbox);
/* Change value of a property. Property concept is useful to grant to objects infinite
extensibility while retaining the same simple API */
int soundbox_set_property(soundbox_t *soundbox,
soundbox_property_id_t property,
const soundbox_property_value_t *value);
/* Read value of a property */
int soundbox_get_property(soundbox_t *soundbox,
soundbox_property_id_t property,
soundbox_property_value_t *value);
/* Obtain info for a property (accepted values, type, etc.) */
int soundbox_query_property(soundbox_t *soundbox,
soundbox_property_id_t property,
soundbox_property_info_t *info);
int soundbox_get_port(soundbox_t *soundbox, soundbox_port_id_t id,
soundbox_port_t **port);
/* Properties count */
#define SOUNDBOX_PROPERTY_PROPERTIES
/* box has real-time dependency when running (hardware PCM soundbox is a
typical example) */
#define SOUNDBOX_PROPERTY_REALTIME
/* state of the soundbox (running, stopped, disabled).
In disabled state the soundbox eat all the data and give out silence. */
#define SOUNDBOX_PROPERTY_STATE
/* Ports count */
#define SOUNDBOX_PROPERTY_PORTS
/* Panels count */
#define SOUNDBOX_PROPERTY_PANELS
/* Parallelization strategy: by channels or by frames */
#define SOUNDBOX_PROPERTY_WORKERS_MODE
/* Parallel workers count */
#define SOUNDBOX_PROPERTY_WORKERS
/********/
/* PORT */
/********/
/* Change value of a property */
int soundbox_port_set_property(soundbox_port_t *port,
soundbox_port_property_id_t property,
const soundbox_port_property_value_t *value);
/* Read value of a property */
int soundbox_port_get_property(soundbox_port_t *port,
soundbox_port_property_id_t property,
soundbox_port_property_value_t *value);
/* Obtain info for a property (accepted values, type, etc.) */
int soundbox_port_query_property(soundbox_port_t *port,
soundbox_port_property_id_t property,
soundbox_port_property_info_t *info);
/* Make two port to share the same buffer */
int soundbox_port_link(soundbox_port_t *port1, soundbox_port_t *port2);
/* Properties count */
#define SOUNDBOX_PORT_PROPERTY_PROPERTIES
/* Port has a poll descriptor associated to its ready condition */
#define SOUNDBOX_PORT_PROPERTY_POLL
/* Poll file descriptor */
#define SOUNDBOX_PORT_PROPERTY_POLL_FD
/* Channels count */
#define SOUNDBOX_PORT_PROPERTY_CHANNELS
/* Frame rate */
#define SOUNDBOX_PORT_PROPERTY_RATE
/* Data format */
#define SOUNDBOX_PORT_PROPERTY_FORMAT
/* Port direction input, output */
#define SOUNDBOX_PORT_PROPERTY_DIRECTION
/* Input port buffer is marked reusable for output (in-place plugin) */
#define SOUNDBOX_PORT_PROPERTY_INPUT_REUSE
/* Output mode (set, add) */
#define SOUNDBOX_PORT_PROPERTY_OUTPUT_MODE
/* Output gain */
#define SOUNDBOX_PORT_PROPERTY_OUTPUT_GAIN
/* Port buffer area shape */
#define SOUNDBOX_PORT_PROPERTY_BUFFER_SHAPE
/* Port buffer size */
#define SOUNDBOX_PORT_PROPERTY_BUFFER_SIZE
/* Min available frames for port ready condition */
#define SOUNDBOX_PORT_PROPERTY_AVAIL_MIN
/********/
/* FLOW */
/********/
typedef unsigned long soundbox_uframes_t;
typedef long soundbox_sframes_t;
typedef struct _soundbox_channel_area {
/* base address of channel samples */
void *addr;
/* offset to first sample in bits */
unsigned int first;
/* samples distance in bits */
unsigned int step;
};
/* Open a data flow associated to a port */
int soundbox_flow_open(soundbox_flow_t **flow, soundbox_flow_id_t *id,
soundbox_flow_args_t *args);
/* Close a data flow handle */
int soundbox_flow_close(soundbox_flow_t *flow);
/* Wait for ready condition to happens */
int soundbox_flow_wait(soundbox_flow_t *flow);
/* Return number of frames available */
soundbox_sframes_t sounbox_flow_avail(soundbox_flow_t *flow);
/* Begin to read/write */
int soundbox_flow_begin(soundbox_flow_t *flow, soundbox_channel_area_t **areas,
soundbox_uframes_t *offset, soundbox_uframes_t *frames);
/* Read/write has completed. xruns are reported here */
int soundbox_flow_commit(soundbox_flow_t *flow, soundbox_uframes_t offset,
soundbox_uframes_t frames);
/* Change value of a property */
int soundbox_flow_set_property(soundbox_flow_t *flow,
soundbox_flow_property_id_t property,
const soundbox_flow_property_value_t *value);
/* Read value of a property */
int soundbox_flow_get_property(soundbox_flow_t *flow,
soundbox_flow_property_id_t property,
soundbox_flow_property_value_t *value);
/* Obtain info for a property (accepted values, type, etc.) */
int soundbox_flow_query_property(soundbox_flow_t *flow,
soundbox_flow_property_id_t property,
soundbox_flow_property_info_t *info);
/* Properties count */
#define SOUNDBOX_FLOW_PROPERTY_PROPERTIES
/*
* --------------------------------------------------------------------------
* Soundbox API ends here.
* --------------------------------------------------------------------------
*/
/*
* The following is an optional API for access controls inside a running object
* without to hurt its real time property.
*/
/*********/
/* PANEL */
/*********/
/* Get access to a panel */
int soundpanel_open(soundpanel_t **panel, soundpanel_id_t *id,
soundpanel_args_t *args);
/* Close access to a panel */
int soundpanel_close(soundpanel_t *panel);
/* Change value of a property */
int soundpanel_set_property(soundpanel_t *panel,
soundpanel_property_id_t property,
const soundpanel_property_value_t *value);
/* Read value of a property */
int soundpanel_get_property(soundpanel_t *panel,
soundpanel_property_id_t property,
soundpanel_property_value_t *value);
/* Obtain info for a property (accepted values, type, etc.) */
int soundpanel_query_property(soundpanel_t *panel,
soundpanel_property_id_t property,
soundpanel_property_info_t *info);
/* Panel client call this before to write one or more controls.
This may block if another client is making a transaction */
int soundpanel_write_begin(soundpanel_t *panel);
/* Panel client call this to assert that current control state is congruent */
int soundpanel_write_commit(soundpanel_t *panel);
/
/* Panel client call this before to read one or more controls */
int soundpanel_read_begin(soundpanel_t *panel, void **cookie);
/* Panel client call this to verify that controls read are congruent */
int soundpanel_read_verify(soundpanel_t *panel, void *cookie);
/* Obtain an handle for a control */
int soundpanel_get_control(soundpanel_t *panel,
soundpanel_control_id_t id,
soundpanel_control_t **control);
/* Properties count */
#define SOUNDPANEL_PROPERTY_PROPERTIES
/* Controls count */
#define SOUNDPANEL_PROPERTY_CONTROLS
/* Panel is available for use via shm */
#define SOUNDPANEL_PROPERTY_SHM
/* shm area key */
#define SOUNDPANEL_PROPERTY_SHM_KEY
/* shm area owner */
#define SOUNDPANEL_PROPERTY_SHM_OWNER
/* shm area group */
#define SOUNDPANEL_PROPERTY_SHM_GROUP
/* shm area permissions */
#define SOUNDPANEL_PROPERTY_SHM_PERMS
/***********/
/* CONTROL */
/***********/
/* Change value of a property */
int soundpanel_control_set_property(soundpanel_control_t *control,
soundpanel_control_property_id_t property,
const soundpanel_control_property_value_t *value);
/* Read value of a property */
int soundpanel_control_get_property(soundpanel_control_t *control,
soundpanel_control_property_id_t property,
soundpanel_control_property_value_t *value);
/* Obtain info for a property (accepted values, type, etc.) */
int soundpanel_control_query_property(soundpanel_control_t *control,
soundpanel_control_property_id_t property,
soundpanel_control_property_info_t *info);
/* Properties count */
#define SOUNDPANEL_CONTROL_PROPERTY_PROPERTIES
/* Control type */
#define SOUNDPANEL_CONTROL_TYPE
/* Control widget hint */
#define SOUNDPANEL_CONTROL_WIDGET
/* Control slots count */
#define SOUNDPANEL_CONTROL_SLOTS
/* Control value */
#define SOUNDPANEL_CONTROL_VALUE(slot)
/*
* --------------------------------------------------------------------------
* Panel API ends here.
* --------------------------------------------------------------------------
*/
