intern/audaspace/intern/AUD_IReader.h

   1 /*
   2  * $Id$
   3  *
   4  * ***** BEGIN GPL LICENSE BLOCK *****
   5  *
   6  * Copyright 2009-2011 Jörg Hermann Müller
   7  *
   8  * This file is part of AudaSpace.
   9  *
  10  * Audaspace is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * AudaSpace is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with Audaspace; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  *
  24  * ***** END GPL LICENSE BLOCK *****
  25  */
  26
  27 /** \file audaspace/intern/AUD_IReader.h
  28  *  \ingroup audaspaceintern
  29  */
  30
  31
  32 #ifndef AUD_IREADER
  33 #define AUD_IREADER
  34
  35 #include "AUD_Space.h"
  36
  37 /**
  38  * This class represents a sound source as stream or as buffer which can be read
  39  * for example by another reader, a device or whatever.
  40  */
  41 class AUD_IReader
  42 {
  43 public:
  44         /**
  45          * Destroys the reader.
  46          */
  47         virtual ~AUD_IReader(){}
  48
  49         /**
  50          * Tells whether the source provides seeking functionality or not.
  51          * \warning This doesn't mean that the seeking always has to succeed.
  52          * \return Always returns true for readers of buffering types.
  53          */
  54         virtual bool isSeekable() const=0;
  55
  56         /**
  57          * Seeks to a specific position in the source.
  58          * \param position The position to seek for measured in samples. To get
  59          *        from a given time to the samples you simply have to multiply the
  60          *        time value in seconds with the sample rate of the reader.
  61          * \warning This may work or not, depending on the actual reader.
  62          */
  63         virtual void seek(int position)=0;
  64
  65         /**
  66          * Returns an approximated length of the source in samples.
  67          * \return The length as sample count. May be negative if unknown.
  68          */
  69         virtual int getLength() const=0;
  70
  71         /**
  72          * Returns the position of the source as a sample count value.
  73          * \return The current position in the source. A negative value indicates
  74          *         that the position is unknown.
  75          * \warning The value returned doesn't always have to be correct for readers,
  76          *          especially after seeking.
  77          */
  78         virtual int getPosition() const=0;
  79
  80         /**
  81          * Returns the specification of the reader.
  82          * \return The AUD_Specs structure.
  83          */
  84         virtual AUD_Specs getSpecs() const=0;
  85
  86         /**
  87          * Request to read the next length samples out of the source.
  88          * The buffer supplied has the needed size.
  89          * \param[in,out] length The count of samples that should be read. Shall
  90          *                contain the real count of samples after reading, in case
  91          *                there were only fewer samples available.
  92          *                A smaller value also indicates the end of the reader.
  93          * \param[out] eos End of stream, whether the end is reached or not.
  94          * \param[in] buffer The pointer to the buffer to read into.
  95          */
  96         virtual void read(int& length, bool& eos, sample_t* buffer)=0;
  97 };
  98
  99 #endif //AUD_IREADER