NBAIO.h revision 2b7b910f4b417ab3930379298f538d0dfc857e88
125b3c049e70834cf33790a28643ab058b507b35cBen Cheng/* 225b3c049e70834cf33790a28643ab058b507b35cBen Cheng * Copyright (C) 2012 The Android Open Source Project 325b3c049e70834cf33790a28643ab058b507b35cBen Cheng * 425b3c049e70834cf33790a28643ab058b507b35cBen Cheng * Licensed under the Apache License, Version 2.0 (the "License"); 525b3c049e70834cf33790a28643ab058b507b35cBen Cheng * you may not use this file except in compliance with the License. 625b3c049e70834cf33790a28643ab058b507b35cBen Cheng * You may obtain a copy of the License at 725b3c049e70834cf33790a28643ab058b507b35cBen Cheng * 825b3c049e70834cf33790a28643ab058b507b35cBen Cheng * http://www.apache.org/licenses/LICENSE-2.0 925b3c049e70834cf33790a28643ab058b507b35cBen Cheng * 1025b3c049e70834cf33790a28643ab058b507b35cBen Cheng * Unless required by applicable law or agreed to in writing, software 1125b3c049e70834cf33790a28643ab058b507b35cBen Cheng * distributed under the License is distributed on an "AS IS" BASIS, 1225b3c049e70834cf33790a28643ab058b507b35cBen Cheng * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1325b3c049e70834cf33790a28643ab058b507b35cBen Cheng * See the License for the specific language governing permissions and 1425b3c049e70834cf33790a28643ab058b507b35cBen Cheng * limitations under the License. 1525b3c049e70834cf33790a28643ab058b507b35cBen Cheng */ 1625b3c049e70834cf33790a28643ab058b507b35cBen Cheng 1725b3c049e70834cf33790a28643ab058b507b35cBen Cheng#ifndef ANDROID_AUDIO_NBAIO_H 1825b3c049e70834cf33790a28643ab058b507b35cBen Cheng#define ANDROID_AUDIO_NBAIO_H 1925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 2025b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Non-blocking audio I/O interface 2125b3c049e70834cf33790a28643ab058b507b35cBen Cheng// 2225b3c049e70834cf33790a28643ab058b507b35cBen Cheng// This header file has the abstract interfaces only. Concrete implementation classes are declared 2325b3c049e70834cf33790a28643ab058b507b35cBen Cheng// elsewhere. Implementations _should_ be non-blocking for all methods, especially read() and 2425b3c049e70834cf33790a28643ab058b507b35cBen Cheng// write(), but this is not enforced. In general, implementations do not need to be multi-thread 2525b3c049e70834cf33790a28643ab058b507b35cBen Cheng// safe, and any exceptions are noted in the particular implementation. 2625b3c049e70834cf33790a28643ab058b507b35cBen Cheng 2725b3c049e70834cf33790a28643ab058b507b35cBen Cheng#include <limits.h> 2825b3c049e70834cf33790a28643ab058b507b35cBen Cheng#include <stdlib.h> 2925b3c049e70834cf33790a28643ab058b507b35cBen Cheng#include <utils/Errors.h> 3025b3c049e70834cf33790a28643ab058b507b35cBen Cheng#include <utils/RefBase.h> 3125b3c049e70834cf33790a28643ab058b507b35cBen Cheng#include <media/AudioTimestamp.h> 3225b3c049e70834cf33790a28643ab058b507b35cBen Cheng#include <system/audio.h> 3325b3c049e70834cf33790a28643ab058b507b35cBen Cheng 3425b3c049e70834cf33790a28643ab058b507b35cBen Chengnamespace android { 3525b3c049e70834cf33790a28643ab058b507b35cBen Cheng 3625b3c049e70834cf33790a28643ab058b507b35cBen Cheng// In addition to the usual status_t 3725b3c049e70834cf33790a28643ab058b507b35cBen Chengenum { 3825b3c049e70834cf33790a28643ab058b507b35cBen Cheng NEGOTIATE = 0x80000010, // Must (re-)negotiate format. For negotiate() only, the offeree 3925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // doesn't accept offers, and proposes counter-offers 4025b3c049e70834cf33790a28643ab058b507b35cBen Cheng OVERRUN = 0x80000011, // availableToRead(), read(), or readVia() detected lost input due 4125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // to overrun; an event is counted and the caller should re-try 4225b3c049e70834cf33790a28643ab058b507b35cBen Cheng UNDERRUN = 0x80000012, // availableToWrite(), write(), or writeVia() detected a gap in 4325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // output due to underrun (not being called often enough, or with 4425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // enough data); an event is counted and the caller should re-try 4525b3c049e70834cf33790a28643ab058b507b35cBen Cheng}; 4625b3c049e70834cf33790a28643ab058b507b35cBen Cheng 4725b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Negotiation of format is based on the data provider and data sink, or the data consumer and 4825b3c049e70834cf33790a28643ab058b507b35cBen Cheng// data source, exchanging prioritized arrays of offers and counter-offers until a single offer is 4925b3c049e70834cf33790a28643ab058b507b35cBen Cheng// mutually agreed upon. Each offer is an NBAIO_Format. For simplicity and performance, 5025b3c049e70834cf33790a28643ab058b507b35cBen Cheng// NBAIO_Format is a typedef that ties together the most important combinations of the various 5125b3c049e70834cf33790a28643ab058b507b35cBen Cheng// attributes, rather than a struct with separate fields for format, sample rate, channel count, 5225b3c049e70834cf33790a28643ab058b507b35cBen Cheng// interleave, packing, alignment, etc. The reason is that NBAIO_Format tries to abstract out only 5325b3c049e70834cf33790a28643ab058b507b35cBen Cheng// the combinations that are actually needed within AudioFlinger. If the list of combinations grows 5425b3c049e70834cf33790a28643ab058b507b35cBen Cheng// too large, then this decision should be re-visited. 5525b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Sample rate and channel count are explicit, PCM interleaved 16-bit is assumed. 5625b3c049e70834cf33790a28643ab058b507b35cBen Chengstruct NBAIO_Format { 5725b3c049e70834cf33790a28643ab058b507b35cBen Cheng//private: 5825b3c049e70834cf33790a28643ab058b507b35cBen Cheng unsigned mSampleRate; 5925b3c049e70834cf33790a28643ab058b507b35cBen Cheng unsigned mChannelCount; 6025b3c049e70834cf33790a28643ab058b507b35cBen Cheng audio_format_t mFormat; 6125b3c049e70834cf33790a28643ab058b507b35cBen Cheng ssize_t mFrameSize; 6225b3c049e70834cf33790a28643ab058b507b35cBen Cheng}; 6325b3c049e70834cf33790a28643ab058b507b35cBen Cheng 6425b3c049e70834cf33790a28643ab058b507b35cBen Chengextern const NBAIO_Format Format_Invalid; 6525b3c049e70834cf33790a28643ab058b507b35cBen Cheng 6625b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Return the frame size of an NBAIO_Format in bytes 6725b3c049e70834cf33790a28643ab058b507b35cBen Chengsize_t Format_frameSize(const NBAIO_Format& format); 6825b3c049e70834cf33790a28643ab058b507b35cBen Cheng 6925b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Return the frame size of an NBAIO_Format as a bit shift 7025b3c049e70834cf33790a28643ab058b507b35cBen Cheng// or -1 if frame size is not a power of 2 7125b3c049e70834cf33790a28643ab058b507b35cBen Chengint Format_frameBitShift(const NBAIO_Format& format); 7225b3c049e70834cf33790a28643ab058b507b35cBen Cheng 7325b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Convert a sample rate in Hz and channel count to an NBAIO_Format 7425b3c049e70834cf33790a28643ab058b507b35cBen Cheng// FIXME Remove the default value of AUDIO_FORMAT_PCM_16_BIT, and rename 7525b3c049e70834cf33790a28643ab058b507b35cBen ChengNBAIO_Format Format_from_SR_C(unsigned sampleRate, unsigned channelCount, 7625b3c049e70834cf33790a28643ab058b507b35cBen Cheng audio_format_t format = AUDIO_FORMAT_PCM_16_BIT); 7725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 7825b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Return the sample rate in Hz of an NBAIO_Format 7925b3c049e70834cf33790a28643ab058b507b35cBen Chengunsigned Format_sampleRate(const NBAIO_Format& format); 8025b3c049e70834cf33790a28643ab058b507b35cBen Cheng 8125b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Return the channel count of an NBAIO_Format 8225b3c049e70834cf33790a28643ab058b507b35cBen Chengunsigned Format_channelCount(const NBAIO_Format& format); 8325b3c049e70834cf33790a28643ab058b507b35cBen Cheng 8425b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Callbacks used by NBAIO_Sink::writeVia() and NBAIO_Source::readVia() below. 8525b3c049e70834cf33790a28643ab058b507b35cBen Chengtypedef ssize_t (*writeVia_t)(void *user, void *buffer, size_t count); 8625b3c049e70834cf33790a28643ab058b507b35cBen Chengtypedef ssize_t (*readVia_t)(void *user, const void *buffer, 8725b3c049e70834cf33790a28643ab058b507b35cBen Cheng size_t count, int64_t readPTS); 8825b3c049e70834cf33790a28643ab058b507b35cBen Cheng 8925b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Check whether an NBAIO_Format is valid 9025b3c049e70834cf33790a28643ab058b507b35cBen Chengbool Format_isValid(const NBAIO_Format& format); 9125b3c049e70834cf33790a28643ab058b507b35cBen Cheng 9225b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Compare two NBAIO_Format values 9325b3c049e70834cf33790a28643ab058b507b35cBen Chengbool Format_isEqual(const NBAIO_Format& format1, const NBAIO_Format& format2); 9425b3c049e70834cf33790a28643ab058b507b35cBen Cheng 9525b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Abstract class (interface) representing a data port. 9625b3c049e70834cf33790a28643ab058b507b35cBen Chengclass NBAIO_Port : public RefBase { 9725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 9825b3c049e70834cf33790a28643ab058b507b35cBen Chengpublic: 9925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 10025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // negotiate() must called first. The purpose of negotiate() is to check compatibility of 10125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // formats, not to automatically adapt if they are incompatible. It's the responsibility of 10225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // whoever sets up the graph connections to make sure formats are compatible, and this method 10325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // just verifies that. The edges are "dumb" and don't attempt to adapt to bad connections. 10425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // How it works: offerer proposes an array of formats, in descending order of preference from 10525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // offers[0] to offers[numOffers - 1]. If offeree accepts one of these formats, it returns 10625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // the index of that offer. Otherwise, offeree sets numCounterOffers to the number of 10725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // counter-offers (up to a maximumum of the entry value of numCounterOffers), fills in the 10825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // provided array counterOffers[] with its counter-offers, in descending order of preference 10925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // from counterOffers[0] to counterOffers[numCounterOffers - 1], and returns NEGOTIATE. 11025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Note that since the offerer allocates space for counter-offers, but only the offeree knows 11125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // how many counter-offers it has, there may be insufficient space for all counter-offers. 11225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // In that case, the offeree sets numCounterOffers to the requested number of counter-offers 11325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // (which is greater than the entry value of numCounterOffers), fills in as many of the most 11425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // important counterOffers as will fit, and returns NEGOTIATE. As this implies a re-allocation, 11525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // it should be used as a last resort. It is preferable for the offerer to simply allocate a 11625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // larger space to begin with, and/or for the offeree to tolerate a smaller space than desired. 11725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Alternatively, the offerer can pass NULL for offers and counterOffers, and zero for 11825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // numOffers. This indicates that it has not allocated space for any counter-offers yet. 11925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // In this case, the offerree should set numCounterOffers appropriately and return NEGOTIATE. 12025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Then the offerer will allocate the correct amount of memory and retry. 12125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Format_Invalid is not allowed as either an offer or counter-offer. 12225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Returns: 12325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // >= 0 Offer accepted. 12425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE No offer accepted, and counter-offer(s) optionally made. See above for details. 12525b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers, 12625b3c049e70834cf33790a28643ab058b507b35cBen Cheng NBAIO_Format counterOffers[], size_t& numCounterOffers); 12725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 12825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return the current negotiated format, or Format_Invalid if negotiation has not been done, 12925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // or if re-negotiation is required. 13025b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual NBAIO_Format format() const { return mNegotiated ? mFormat : Format_Invalid; } 13125b3c049e70834cf33790a28643ab058b507b35cBen Cheng 13225b3c049e70834cf33790a28643ab058b507b35cBen Chengprotected: 13325b3c049e70834cf33790a28643ab058b507b35cBen Cheng NBAIO_Port(const NBAIO_Format& format) : mNegotiated(false), mFormat(format), 13425b3c049e70834cf33790a28643ab058b507b35cBen Cheng mBitShift(Format_frameBitShift(format)), 13525b3c049e70834cf33790a28643ab058b507b35cBen Cheng mFrameSize(Format_frameSize(format)) { } 13625b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ~NBAIO_Port() { } 13725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 13825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Implementations are free to ignore these if they don't need them 13925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 14025b3c049e70834cf33790a28643ab058b507b35cBen Cheng bool mNegotiated; // mNegotiated implies (mFormat != Format_Invalid) 14125b3c049e70834cf33790a28643ab058b507b35cBen Cheng NBAIO_Format mFormat; // (mFormat != Format_Invalid) does not imply mNegotiated 14225b3c049e70834cf33790a28643ab058b507b35cBen Cheng size_t mBitShift; // assign in parallel with any assignment to mFormat 14325b3c049e70834cf33790a28643ab058b507b35cBen Cheng size_t mFrameSize; // assign in parallel with any assignment to mFormat 14425b3c049e70834cf33790a28643ab058b507b35cBen Cheng}; 14525b3c049e70834cf33790a28643ab058b507b35cBen Cheng 14625b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Abstract class (interface) representing a non-blocking data sink, for use by a data provider. 14725b3c049e70834cf33790a28643ab058b507b35cBen Chengclass NBAIO_Sink : public NBAIO_Port { 14825b3c049e70834cf33790a28643ab058b507b35cBen Cheng 14925b3c049e70834cf33790a28643ab058b507b35cBen Chengpublic: 15025b3c049e70834cf33790a28643ab058b507b35cBen Cheng 15125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // For the next two APIs: 15225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically. 15325b3c049e70834cf33790a28643ab058b507b35cBen Cheng 15425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return the number of frames written successfully since construction. 15525b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual size_t framesWritten() const { return mFramesWritten; } 15625b3c049e70834cf33790a28643ab058b507b35cBen Cheng 15725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Number of frames lost due to underrun since construction. 15825b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual size_t framesUnderrun() const { return 0; } 15925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 16025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Number of underruns since construction, where a set of contiguous lost frames is one event. 16125b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual size_t underruns() const { return 0; } 16225b3c049e70834cf33790a28643ab058b507b35cBen Cheng 16325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Estimate of number of frames that could be written successfully now without blocking. 16425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // When a write() is actually attempted, the implementation is permitted to return a smaller or 16525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // larger transfer count, however it will make a good faith effort to give an accurate estimate. 16625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Errors: 16725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE (Re-)negotiation is needed. 16825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up. 16925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // An underrun event is counted, and the caller should re-try this operation. 17025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // WOULD_BLOCK Determining how many frames can be written without blocking would itself block. 17125b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t availableToWrite() const { return SSIZE_MAX; } 17225b3c049e70834cf33790a28643ab058b507b35cBen Cheng 17325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Transfer data to sink from single input buffer. Implies a copy. 17425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 17525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // buffer Non-NULL buffer owned by provider. 17625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // count Maximum number of frames to transfer. 17725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 17825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // > 0 Number of frames successfully transferred prior to first error. 17925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // = 0 Count was zero. 18025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // < 0 status_t error occurred prior to the first frame transfer. 18125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Errors: 18225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE (Re-)negotiation is needed. 18325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // WOULD_BLOCK No frames can be transferred without blocking. 18425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up. 18525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // An underrun event is counted, and the caller should re-try this operation. 18625b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t write(const void *buffer, size_t count) = 0; 18725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 18825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Transfer data to sink using a series of callbacks. More suitable for zero-fill, synthesis, 18925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // and non-contiguous transfers (e.g. circular buffer or writev). 19025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 19125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // via Callback function that the sink will call as many times as needed to consume data. 19225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // total Estimate of the number of frames the provider has available. This is an estimate, 19325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // and it can provide a different number of frames during the series of callbacks. 19425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // user Arbitrary void * reserved for data provider. 19525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // block Number of frames per block, that is a suggested value for 'count' in each callback. 19625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Zero means no preference. This parameter is a hint only, and may be ignored. 19725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 19825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // > 0 Total number of frames successfully transferred prior to first error. 19925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // = 0 Count was zero. 20025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // < 0 status_t error occurred prior to the first frame transfer. 20125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Errors: 20225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE (Re-)negotiation is needed. 20325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // WOULD_BLOCK No frames can be transferred without blocking. 20425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up. 20525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // An underrun event is counted, and the caller should re-try this operation. 20625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // 20725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // The 'via' callback is called by the data sink as follows: 20825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 20925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // user Arbitrary void * reserved for data provider. 21025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // buffer Non-NULL buffer owned by sink that callback should fill in with data, 21125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // up to a maximum of 'count' frames. 21225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // count Maximum number of frames to transfer during this callback. 21325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 21425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // > 0 Number of frames successfully transferred during this callback prior to first error. 21525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // = 0 Count was zero. 21625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // < 0 status_t error occurred prior to the first frame transfer during this callback. 21725b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block = 0); 21825b3c049e70834cf33790a28643ab058b507b35cBen Cheng 21925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Get the time (on the LocalTime timeline) at which the first frame of audio of the next write 22025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // operation to this sink will be eventually rendered by the HAL. 22125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 22225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // ts A pointer pointing to the int64_t which will hold the result. 22325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 22425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // OK Everything went well, *ts holds the time at which the first audio frame of the next 22525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // write operation will be rendered, or AudioBufferProvider::kInvalidPTS if this sink 22625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // does not know the answer for some reason. Sinks which eventually lead to a HAL 22725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // which implements get_next_write_timestamp may return Invalid temporarily if the DMA 22825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // output of the audio driver has not started yet. Sinks which lead to a HAL which 22925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // does not implement get_next_write_timestamp, or which don't lead to a HAL at all, 23025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // will always return kInvalidPTS. 23125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // <other> Something unexpected happened internally. Check the logs and start debugging. 23225b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual status_t getNextWriteTimestamp(int64_t *ts) { return INVALID_OPERATION; } 23325b3c049e70834cf33790a28643ab058b507b35cBen Cheng 23425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Returns NO_ERROR if a timestamp is available. The timestamp includes the total number 23525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // of frames presented to an external observer, together with the value of CLOCK_MONOTONIC 23625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // as of this presentation count. 23725b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual status_t getTimestamp(AudioTimestamp& timestamp) { return INVALID_OPERATION; } 23825b3c049e70834cf33790a28643ab058b507b35cBen Cheng 23925b3c049e70834cf33790a28643ab058b507b35cBen Chengprotected: 24025b3c049e70834cf33790a28643ab058b507b35cBen Cheng NBAIO_Sink(const NBAIO_Format& format = Format_Invalid) : NBAIO_Port(format), mFramesWritten(0) { } 24125b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ~NBAIO_Sink() { } 24225b3c049e70834cf33790a28643ab058b507b35cBen Cheng 24325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Implementations are free to ignore these if they don't need them 24425b3c049e70834cf33790a28643ab058b507b35cBen Cheng size_t mFramesWritten; 24525b3c049e70834cf33790a28643ab058b507b35cBen Cheng}; 24625b3c049e70834cf33790a28643ab058b507b35cBen Cheng 24725b3c049e70834cf33790a28643ab058b507b35cBen Cheng// Abstract class (interface) representing a non-blocking data source, for use by a data consumer. 24825b3c049e70834cf33790a28643ab058b507b35cBen Chengclass NBAIO_Source : public NBAIO_Port { 24925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 25025b3c049e70834cf33790a28643ab058b507b35cBen Chengpublic: 25125b3c049e70834cf33790a28643ab058b507b35cBen Cheng 25225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // For the next two APIs: 25325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically. 25425b3c049e70834cf33790a28643ab058b507b35cBen Cheng 25525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Number of frames read successfully since construction. 25625b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual size_t framesRead() const { return mFramesRead; } 25725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 25825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Number of frames lost due to overrun since construction. 25925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Not const because implementations may need to do I/O. 26025b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual size_t framesOverrun() /*const*/ { return 0; } 26125b3c049e70834cf33790a28643ab058b507b35cBen Cheng 26225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Number of overruns since construction, where a set of contiguous lost frames is one event. 26325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Not const because implementations may need to do I/O. 26425b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual size_t overruns() /*const*/ { return 0; } 26525b3c049e70834cf33790a28643ab058b507b35cBen Cheng 26625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Estimate of number of frames that could be read successfully now. 26725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // When a read() is actually attempted, the implementation is permitted to return a smaller or 26825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // larger transfer count, however it will make a good faith effort to give an accurate estimate. 26925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Errors: 27025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE (Re-)negotiation is needed. 27125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // OVERRUN One or more frames were lost due to overrun, try again to read more recent data. 27225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // WOULD_BLOCK Determining how many frames can be read without blocking would itself block. 27325b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t availableToRead() { return SSIZE_MAX; } 27425b3c049e70834cf33790a28643ab058b507b35cBen Cheng 27525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Transfer data from source into single destination buffer. Implies a copy. 27625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 27725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // buffer Non-NULL destination buffer owned by consumer. 27825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // count Maximum number of frames to transfer. 27925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // readPTS The presentation time (on the LocalTime timeline) for which data 28025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // is being requested, or kInvalidPTS if not known. 28125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 28225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // > 0 Number of frames successfully transferred prior to first error. 28325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // = 0 Count was zero. 28425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // < 0 status_t error occurred prior to the first frame transfer. 28525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Errors: 28625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE (Re-)negotiation is needed. 28725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // WOULD_BLOCK No frames can be transferred without blocking. 28825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // OVERRUN read() has not been called frequently enough, or with enough frames to keep up. 28925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // One or more frames were lost due to overrun, try again to read more recent data. 29025b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t read(void *buffer, size_t count, int64_t readPTS) = 0; 29125b3c049e70834cf33790a28643ab058b507b35cBen Cheng 29225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Transfer data from source using a series of callbacks. More suitable for zero-fill, 29325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // synthesis, and non-contiguous transfers (e.g. circular buffer or readv). 29425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 29525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // via Callback function that the source will call as many times as needed to provide data. 29625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // total Estimate of the number of frames the consumer desires. This is an estimate, 29725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // and it can consume a different number of frames during the series of callbacks. 29825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // user Arbitrary void * reserved for data consumer. 29925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // readPTS The presentation time (on the LocalTime timeline) for which data 30025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // is being requested, or kInvalidPTS if not known. 30125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // block Number of frames per block, that is a suggested value for 'count' in each callback. 30225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Zero means no preference. This parameter is a hint only, and may be ignored. 30325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 30425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // > 0 Total number of frames successfully transferred prior to first error. 30525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // = 0 Count was zero. 30625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // < 0 status_t error occurred prior to the first frame transfer. 30725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Errors: 30825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // NEGOTIATE (Re-)negotiation is needed. 30925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // WOULD_BLOCK No frames can be transferred without blocking. 31025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // OVERRUN read() has not been called frequently enough, or with enough frames to keep up. 31125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // One or more frames were lost due to overrun, try again to read more recent data. 31225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // 31325b3c049e70834cf33790a28643ab058b507b35cBen Cheng // The 'via' callback is called by the data source as follows: 31425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Inputs: 31525b3c049e70834cf33790a28643ab058b507b35cBen Cheng // user Arbitrary void * reserved for data consumer. 31625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // dest Non-NULL buffer owned by source that callback should consume data from, 31725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // up to a maximum of 'count' frames. 31825b3c049e70834cf33790a28643ab058b507b35cBen Cheng // count Maximum number of frames to transfer during this callback. 31925b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Return value: 32025b3c049e70834cf33790a28643ab058b507b35cBen Cheng // > 0 Number of frames successfully transferred during this callback prior to first error. 32125b3c049e70834cf33790a28643ab058b507b35cBen Cheng // = 0 Count was zero. 32225b3c049e70834cf33790a28643ab058b507b35cBen Cheng // < 0 status_t error occurred prior to the first frame transfer during this callback. 32325b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ssize_t readVia(readVia_t via, size_t total, void *user, 32425b3c049e70834cf33790a28643ab058b507b35cBen Cheng int64_t readPTS, size_t block = 0); 32525b3c049e70834cf33790a28643ab058b507b35cBen Cheng 32625b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Invoked asynchronously by corresponding sink when a new timestamp is available. 32725b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Default implementation ignores the timestamp. 32825b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual void onTimestamp(const AudioTimestamp& timestamp) { } 32925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 33025b3c049e70834cf33790a28643ab058b507b35cBen Chengprotected: 33125b3c049e70834cf33790a28643ab058b507b35cBen Cheng NBAIO_Source(const NBAIO_Format& format = Format_Invalid) : NBAIO_Port(format), mFramesRead(0) { } 33225b3c049e70834cf33790a28643ab058b507b35cBen Cheng virtual ~NBAIO_Source() { } 33325b3c049e70834cf33790a28643ab058b507b35cBen Cheng 33425b3c049e70834cf33790a28643ab058b507b35cBen Cheng // Implementations are free to ignore these if they don't need them 33525b3c049e70834cf33790a28643ab058b507b35cBen Cheng size_t mFramesRead; 33625b3c049e70834cf33790a28643ab058b507b35cBen Cheng}; 33725b3c049e70834cf33790a28643ab058b507b35cBen Cheng 33825b3c049e70834cf33790a28643ab058b507b35cBen Cheng} // namespace android 33925b3c049e70834cf33790a28643ab058b507b35cBen Cheng 34025b3c049e70834cf33790a28643ab058b507b35cBen Cheng#endif // ANDROID_AUDIO_NBAIO_H 34125b3c049e70834cf33790a28643ab058b507b35cBen Cheng