Symbian3/SDK/Source/GUID-06A43E09-CC6D-5799-A0F7-68B5696F4ADB.dita
author Graeme Price <GRAEME.PRICE@NOKIA.COM>
Fri, 15 Oct 2010 14:32:18 +0100
changeset 15 307f4279f433
parent 0 89d6a7a84779
permissions -rw-r--r--
Initial contribution of the Adaptation Documentation.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     6
<!-- Initial Contributors:
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     7
    Nokia Corporation - initial contribution.
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     8
Contributors: 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     9
-->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    10
<!DOCTYPE concept
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    12
<concept xml:lang="en" id="GUID-06A43E09-CC6D-5799-A0F7-68B5696F4ADB"><title>Audio Component Library Overview </title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document provides an overview of the Audio Component Library (ACL) API. </p> <section><title>Purpose</title> <p>The ACL API is an open-ended library of audio processing units. The ACL API is used to define the audio processing units which can be built into an audio stream. </p> <p><b>Audio Component Library API Library Details</b> </p> <p>The ACL API is implemented using a plugin pattern. </p> <p>The DLL that provides the functionality and the library to which your code must link is identified below. </p> <table id="GUID-F7967E7D-066E-5341-9660-D565319B83DC"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>DLL</entry> <entry>LIB</entry> <entry>Short Description</entry> </row> </thead> <tbody><row><entry><p> <filepath> audiocontextfactory.dll</filepath>  </p> </entry> <entry><p> <filepath> audiocontextfactory.lib</filepath>  </p> </entry> <entry><p>These files are used for implementing the ACL API. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Architectural Relationship</title> <p>This API is part of the Advanced Audio Adaptation Framework (A3F). A3F provides a new standardised implementation of DevSound which is configured by default from Symbian OS v9.5 onwards. A3F interacts with a specially customised DevSound (configured as optional) through the ACL API and the <xref href="GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita">Audio Component Framework (ACF) API</xref>. </p> </section> <section><title>Description</title> <p>Audio processing units are logical entities (not directly related to any specific audio hardware) that represent basic audio functions. The ACL API is an open-ended library of such logical audio processing units. The list of audio processing units in the ACL includes: </p> <ul><li id="GUID-8CC2DEB6-99AC-59AF-BE96-666B37B55824"><p>buffer source and sink </p> </li> <li id="GUID-ED8E27D5-C7E2-56CC-8486-6909408E317E"><p>audio device source and sink </p> </li> <li id="GUID-FAF60CA3-3C8D-55EC-A429-A91852EEB4DB"><p>audio codec. </p> </li> </ul> <p>An audio stream links together several audio processing units. The ACL API enables the client to specify an audio stream and the individual audio processing units that it contains. An audio stream represents a connection between: </p> <ul><li id="GUID-EFCC02B3-24C0-59A7-AD12-9BD6AFD5A676"><p>1 source </p> </li> <li id="GUID-9B840546-808A-5586-91B1-6298AFD3C2FD"><p>1 codec (either a decoder or an encoder) </p> </li> <li id="GUID-AE746B34-C3B9-58C4-BB5B-657937DC58C1"><p>0 or 1 gain control </p> </li> <li id="GUID-71FE34AD-B300-5307-8C7A-3125E17B4A67"><p>1 sink. </p> </li> </ul> <p>An audio stream is also responsible for executing audio processing states as requested by the client. The audio processing units contained in an audio stream adapt to state changes as required. The possible states of an audio stream are: </p> <ul><li id="GUID-848DE516-9A98-540F-B31B-7AF5E89B5BA6"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EUninitialized</apiname></xref> - the state an audio stream is in initially. </p> </li> <li id="GUID-2AF888AA-9478-567D-B28F-A403C0326753"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EInitialized</apiname></xref> - the state after a successful initialization request. </p> </li> <li id="GUID-3136A4AF-BFA5-52AA-BA3A-D72485F840DF"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EIdle</apiname></xref> - all resources have been allocated but use no CPU time (other than that expended to put the audio stream into the <codeph>EIdle</codeph> state) is consumed. </p> </li> <li id="GUID-6E0A30BB-CCE3-5FD4-AE22-74836A74B48D"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>EPrimed</apiname></xref> - as with <codeph>EIdle</codeph>, but the audio stream can consume CPU time by filling its buffers. Note that no sound can be played when the audio stream is in <codeph>EPrimed</codeph> state. </p> </li> <li id="GUID-2309CA33-E091-5FB2-BC6C-177F9B1839BC"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EActive</apiname></xref> - all resources have been allocated, as with EIdle and EPrimed, but the audio stream has also started to process the actions requested by the client. </p> </li> <li id="GUID-AB6EAC1B-C87D-5EA4-AE56-ED20CB72973C"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EDead</apiname></xref> - the audio stream can no longer function due to a fatal error. </p> </li> </ul> </section> <section><title>Key Audio Component Library API Classes</title> <p>The ACL API comprises the following key classes: </p> <ul><li id="GUID-D5A112BE-C36C-5BEE-B5C6-66670BCF5F7A"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>MAudioStream</apiname></xref> - the main control interface for the state of an audio stream. </p> </li> </ul> </section> <section><title>Using Audio Component Library API</title> <p>The ACL API can be used to: </p> <ul><li id="GUID-332A1636-54F0-57A9-92F1-4B5233D6D39D"><p>Request that the state of an audio stream is changed to another state. The main state transitions are requested using the following methods: </p> <ul><li id="GUID-21E351C1-6177-57F4-9989-8BCF7077C81F"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Initialize()</apiname></xref> - requests a transition to the <codeph>EInitialized</codeph> state. </p> </li> <li id="GUID-B49E5BA7-BE2C-5A08-B6B3-B848564C89BB"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Load()</apiname></xref> - requests a transition to the <codeph>EIdle</codeph> state. </p> </li> <li id="GUID-8336AC1A-0AE5-5984-888A-8BBFCD7BB559"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Activate()</apiname></xref> - starts the audio processing. </p> </li> <li id="GUID-05EDA606-DAE4-50C1-85BE-270E50B4107C"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Stop()</apiname></xref> - requests a transition to the <codeph>EIdle</codeph> state. </p> </li> <li id="GUID-515E479F-8FF9-5865-8DEA-110C1397AF36"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Unload()</apiname></xref> - prepares the audio stream for releasing the resources reserved for it. </p> </li> <li id="GUID-FF553EB2-D02F-5A2E-A21F-0205F41ABB62"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Uninitialize()</apiname></xref> - requests a transition to the <codeph>EUnitialized</codeph> state. </p> </li> <li id="GUID-5D84D8C6-50B6-56AE-A28C-1658B29F9B76"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Prime()</apiname></xref> - requests a transition to the <codeph>EPrimed</codeph> state. </p> </li> </ul> </li> </ul> </section> <section><title>See Also</title> <p><xref href="GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita">Audio Component Framework Overview</xref>  </p> </section> </conbody></concept>