/* * All-in-one sound boxes external API * Copyright (c) 2001 by Abramo Bagnara * * * 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. * -------------------------------------------------------------------------- */