Changeset 245

Show
Ignore:
Timestamp:
06/05/06 03:05:52 (18 years ago)
Author:
pieterpalmers
Message:

- added doxygen documentation to the make process
- wrote some preliminary documentation

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • branches/libfreebob-2.0/configure.ac

    r199 r245  
    227227 
    228228AC_CONFIG_FILES([Makefile 
     229                 doc/Makefile 
     230                 doc/reference.doxygen 
    229231                 libfreebob/Makefile 
    230232                 src/debugmodule/Makefile 
  • branches/libfreebob-2.0/Makefile.am

    r225 r245  
    1616# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
    1717 
    18 SUBDIRS = libfreebob src tests  
     18SUBDIRS = libfreebob src tests doc 
    1919 
    2020pkgconfigdir = $(libdir)/pkgconfig 
  • branches/libfreebob-2.0/src/iavdevice.h

    r234 r245  
    3535 
    3636 This interface should be used to implement freebob support for a specific device. 
    37   
     37 
    3838*/ 
    3939class IAvDevice { 
     
    4141        virtual ~IAvDevice() {} 
    4242         
    43         /// Returns the ConfigRom of the device node. 
     43        /// Returns the ConfigRom object of the device node. 
    4444        virtual ConfigRom& getConfigRom() const = 0; 
    4545         
    46         /// this is called to discover & configure the device 
     46        /** 
     47         * This is called by the probe function to discover & configure the device 
     48         * 
     49         *  
     50         * @return true if the device was discovered successfully 
     51         */ 
    4752        virtual bool discover() = 0; 
    4853         
     54        /** 
     55         * Set the samping frequency 
     56         * @param samplingFrequency  
     57         * @return true if successfull 
     58         */ 
    4959        virtual bool setSamplingFrequency( ESamplingFrequency samplingFrequency ) = 0; 
     60        /** 
     61         * get the samplingfrequency as an integer 
     62         * @return the sampling frequency as integer 
     63         */ 
    5064        virtual int getSamplingFrequency( ) = 0; 
    5165         
     66    /** 
     67     * This is called by the device manager to give the device 
     68     * a unique ID. 
     69     * 
     70     * The purpose of this is to allow for unique port naming 
     71     * in case there are multiple identical devices on the bus. 
     72     * Some audio API's (e.g. jack) don't work properly when the 
     73     * port names are not unique. 
     74     * 
     75     * Say you have two devices having a port named OutputLeft. 
     76     * This can cause the streaming 
     77     * part to present two OutputLeft ports to the audio API, 
     78     * which won't work. This ID will allow you to construct 
     79     * the port names as 'dev1_OutputLeft' and 'dev2_OutputLeft' 
     80     * 
     81     * \note Currently this is a simple integer that is equal to 
     82     *       the position of the device in the devicemanager's  
     83     *       device list. Therefore it is dependant on the order 
     84     *       in which the devices are detected. The side-effect 
     85     *       of this is that it is dependant on the bus topology 
     86     *       and history (e.g. busresets etc). This makes that 
     87     *       these ID's are not fixed to a specific physical device. 
     88     *       At some point, we will replaced this with a GUID based  
     89     *       approach, which is tied to a physiscal device and is 
     90     *       bus & time independant.  
     91     * 
     92     * @param id  
     93     * @return true if successfull 
     94     */ 
    5295    virtual bool setId(unsigned int id) = 0; 
    5396         
    54         /// obsolete 
     97        /** 
     98         * Constructs an XML description of the device [obsolete] 
     99         * 
     100         * this is a leftover from v1.0 and isn't used 
     101         * just provide an empty implementation that returns true 
     102         * untill it is removed 
     103         * 
     104         * @param deviceNode  
     105         * @return true if successfull 
     106         */ 
    55107        virtual bool addXmlDescription( xmlNodePtr deviceNode ) = 0; 
    56108         
    57         /// debug: outputs the device configuration to stderr/stdout 
     109        /** 
     110         * Outputs the device configuration to stderr/stdout [debug helper] 
     111         * 
     112         * This function prints out a (detailed) description of the  
     113         * device detected, and its configuration. 
     114         */ 
    58115        virtual void showDevice() const = 0; 
    59116         
    60         /** prepare the device 
     117        /**  
     118         * Prepare the device 
    61119         *  \todo when exactly is this called? and what should it do? 
    62120         */ 
    63121        virtual bool prepare() = 0; 
    64122         
    65         /// returns the number of ISO streams implemented/used by this device 
     123        ///  
     124        /** 
     125         * Returns the number of ISO streams implemented/used by this device 
     126         * 
     127         * Most likely this is 2 streams, i.e. one transmit stream and one 
     128         * receive stream. However there are devices that implement more, for  
     129         * example BeBoB's implement 4 streams:  
     130         * - 2 audio streams (1 xmit/1 recv) 
     131         * - 2 sync streams (1 xmit/1 recv), which are an optional sync source 
     132         *   for the device. 
     133         * 
     134         * \note you have to have a StreamProcessor for every stream. I.e. 
     135         *       getStreamProcessorByIndex(i) should return a valid StreamProcessor 
     136         *       for i=0 to i=getStreamCount()-1 
     137         * \note 
     138         * 
     139         * @return  
     140         */ 
    66141        virtual int getStreamCount() = 0; 
    67142         
    68         /** returns the stream processor for the stream with index \ref i 
     143        /**  
     144         * Returns the StreamProcessor object for the stream with index i 
     145         * \note a streamprocessor returned by getStreamProcessorByIndex(i) 
     146         *       cannot be the same object as one returned by 
     147         *       getStreamProcessorByIndex(j) if i isn't equal to j 
     148         * \note you could have two streamprocessors handling the same ISO 
     149         *       channel if that's needed 
    69150         * \param i : Stream index 
    70151         * \pre \ref i smaller than getStreamCount() 
     152         * @return a StreamProcessor object if successfull, NULL otherwise 
    71153         */ 
    72154        virtual FreebobStreaming::StreamProcessor *getStreamProcessorByIndex(int i) = 0; 
    73155         
    74         /** starts the stream with index \ref i 
     156        /**  
     157         * starts the stream with index i 
     158         * 
     159         * This function is called by the streaming layer when this stream should 
     160         * be started, i.e. the device should start sending data or should be prepared to  
     161         * be ready to receive data. 
     162         * 
     163         * It returns the channel number that was assigned for this stream. 
     164         *  
     165         * For BeBoB's this implements the IEC61883 connection management procedure (CMP). 
     166         * This CMP is a way to negotiate the channel that should be used, the bandwidth  
     167         * consumed and to start the device's streaming mode. 
     168         * 
     169         * Note that this IEC61883 CMP is nescessary to allow multiple ISO devices on the bus, 
     170         * because otherwise there is no way to know what ISO channels are already in use. 
     171         * or is there? 
     172         * \note I wouldn't know how to assign channels for devices that don't implement 
     173         *       IEC61883 CMP (like the Motu?). As long as there is only one device on the 
     174         *       bus this is no problem and can be solved with static assignments.  
     175         * 
    75176         * \param i : Stream index 
    76177         * \pre \ref i smaller than getStreamCount() 
     178         * \return the ISO channel number assigned to this stream 
    77179         */ 
    78180        virtual int startStreamByIndex(int i) = 0; 
    79181         
    80         /** stops the stream with index \ref i 
     182        /**  
     183         * stops the stream with index \ref i 
     184         * 
    81185         * \param i : Stream index 
    82186         * \pre \ref i smaller than getStreamCount() 
     187         * \return 0 on success, -1 else 
    83188         */ 
    84189        virtual int stopStreamByIndex(int i) = 0; 
  • branches/libfreebob-2.0/src/libfreebobavc/avc_definitions.h

    r183 r245  
    6868typedef quadlet_t company_id_t; 
    6969 
     70/** 
     71 * \brief the possible sampling frequencies 
     72 */ 
    7073enum ESamplingFrequency { 
    7174    eSF_22050Hz = 0x00, 
     
    8184}; 
    8285 
     86/** 
     87 * \brief Convert from ESamplingFrequency to an integer 
     88 * @param freq  
     89 * @return  
     90 */ 
    8391int convertESamplingFrequency(ESamplingFrequency freq); 
     92/** 
     93 * \brief Convert from integer to ESamplingFrequency 
     94 * @param sampleRate  
     95 * @return  
     96 */ 
    8497ESamplingFrequency parseSampleRate( int sampleRate ); 
    8598 
  • branches/libfreebob-2.0/src/libstreaming/ringbuffer.h

    r200 r245  
    3636/** @file ringbuffer.h 
    3737 * 
    38  * A set of library functions to make lock-free ringbuffers available 
    39  * to JACK clients.  The `capture_client.c' (in the example_clients 
    40  * directory) is a fully functioning user of this API. 
    4138 * 
    4239 * The key attribute of a ringbuffer is that it can be safely accessed