Changeset fbafd2c for doc/develop.rst


Ignore:
Timestamp:
Mar 25, 2017, 12:12:38 PM (8 years ago)
Author:
Paul Brossier <piem@piem.org>
Branches:
sampler
Children:
b201912
Parents:
f8d96f1 (diff), 2a7bcaa (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'master' into sampler

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/develop.rst

    rf8d96f1 rfbafd2c  
    44======================
    55
    6 Read `Contribute`_ to report issues and request new features.
     6Here is a brief overview of the C library.
    77
    8 See `Doxygen documentation`_ for the complete documentation of the C library,
    9 built using `Doxygen <http://www.doxygen.org/>`_.
     8For a more detailed list of available functions, see the `API documentation
     9<https://aubio.org/doc/latest/>`_.
    1010
    11 Below is a brief `Library overview`_.
     11To report issues, ask questions, and request new features, use `Github Issues
     12<https://github.com/aubio/aubio/issues>`_
    1213
    13 Library overview
    14 ----------------
     14Design Basics
     15-------------
    1516
    16 Here is a brief overview of the C library. See also the `Doxygen
    17 documentation`_ for a more detailed list of available functions.
     17The library is written in C and is optimised for speed and portability.
    1818
    19 Vectors and matrix
    20 ``````````````````
    21 
    22 ``fvec_t`` are used to hold vectors of float (``smpl_t``).
    23 
    24 .. literalinclude:: ../tests/src/test-fvec.c
    25    :language: C
    26    :lines: 7
    27 
     19All memory allocations take place in the `new_` methods. Each successful call
     20to `new_` should have a matching call to `del_` to deallocate the object.
    2821
    2922.. code-block:: C
    3023
    31         // set some elements
    32         vec->data[511] = 2.;
    33         vec->data[vec->length-2] = 1.;
     24   // new_ to create an object foobar
     25   aubio_foobar_t * new_aubio_foobar(void * args);
     26   // del_ to delete foobar
     27   void del_aubio_foobar (aubio_foobar_t * foobar);
    3428
    35 Similarly, ``fmat_t`` are used to hold matrix of floats.
     29The main computations are done in the `_do` methods.
    3630
    37 .. literalinclude:: ../tests/src/test-fmat.c
    38    :language: C
    39    :lines: 9-19
     31.. code-block:: C
     32
     33   // _do to process output = foobar(input)
     34   audio_foobar_do (aubio_foobar_t * foobar, fvec_t * input, cvec_t * output);
     35
     36Most parameters can be read and written at any time:
     37
     38.. code-block:: C
     39
     40   // _get_param to get foobar.param
     41   smpl_t aubio_foobar_get_a_parameter (aubio_foobar_t * foobar);
     42   // _set_param to set foobar.param
     43   uint_t aubio_foobar_set_a_parameter (aubio_foobar_t * foobar, smpl_t a_parameter);
     44
     45In some case, more functions are available:
     46
     47.. code-block:: C
     48
     49   // non-real time functions
     50   uint_t aubio_foobar_reset(aubio_foobar_t * t);
     51
     52Basic Types
     53-----------
     54
     55.. code-block:: C
     56
     57    // integers
     58    uint_t n = 10;                 // unsigned
     59    sint_t delay = -90;            // signed
     60
     61    // float
     62    smpl_t a = -90.;               // simple precision
     63    lsmp_t f = 0.024;              // double precision
     64
     65    // vector of floats (simple precision)
     66    fvec_t * vec = new_fvec(n);
     67    vec->data[0] = 1;
     68    vec->data[vec->length-1] = 1.; // vec->data has n elements
     69    fvec_print(vec);
     70    del_fvec(vec);
     71
     72    // complex data
     73    cvec_t * fftgrain = new_cvec(n);
     74    vec->norm[0] = 1.;             // vec->norm has n/2+1 elements
     75    vec->phas[n/2] = 3.1415;       // vec->phas as well
     76    del_cvec(fftgrain);
     77
     78    // matrix
     79    fmat_t * mat = new_fmat (height, length);
     80    mat->data[height-1][0] = 1;    // mat->data has height rows
     81    mat->data[0][length-1] = 10;   // mat->data[0] has length columns
     82    del_fmat(mat);
     83
    4084
    4185Reading a sound file
    42 ````````````````````
    43 In this example, ``aubio_source`` is used to read a media file.
     86--------------------
    4487
    45 First, create the objects we need.
     88In this example, `aubio_source <https://aubio.org/doc/latest/source_8h.html>`_
     89is used to read a media file.
     90
     91First, define a few variables and allocate some memory.
    4692
    4793.. literalinclude:: ../tests/src/io/test-source.c
    … …  
    59105   :lines: 40-44
    60106
    61 At the end of the processing loop, clean-up and de-allocate memory:
     107At the end of the processing loop, memory is deallocated:
    62108
    63109.. literalinclude:: ../tests/src/io/test-source.c
    64110   :language: C
    65    :lines: 50-56
     111   :lines: 55-56
    66112
    67113See the complete example: :download:`test-source.c
    68114<../tests/src/io/test-source.c>`.
    69115
    70 Computing the spectrum
    71 ``````````````````````
     116Computing a spectrum
     117--------------------
    72118
    73119Now let's create a phase vocoder:
    … …  
    81127.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
    82128   :language: C
    83    :lines: 21-35
     129   :lines: 20-37
     130
     131Time to clean up the previously allocated memory:
     132
     133.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
     134   :language: C
     135   :lines: 39-44
    84136
    85137See the complete example: :download:`test-phasevoc.c
    … …  
    91143---------------------
    92144
    93 The latest version of the doxygen documentation is available at:
     145The latest version of the API documentation is built using `Doxygen
     146<http://www.doxygen.org/>`_ and is available at:
    94147
    95     https://aubio.org/doc/latest
     148    https://aubio.org/doc/latest/
    96149
    97150Contribute
    … …  
    100153Please report any issue and feature request at the `Github issue tracker
    101154<https://github.com/aubio/aubio/issues>`_. Patches and pull-requests welcome!
    102 
Note: See TracChangeset for help on using the changeset viewer.