Changeset 67e0eeb for doc


Ignore:
Timestamp:
Mar 24, 2017, 7:38:55 PM (4 years ago)
Author:
Paul Brossier <piem@piem.org>
Branches:
feature/autosink, feature/constantq, feature/pitchshift, feature/pydocstrings, feature/timestretch, master, sampler
Children:
5782f99
Parents:
4da6f20
Message:

doc/develop.rst: improve basics

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/develop.rst

    r4da6f20 r67e0eeb  
    1717The library is written in C and is optimised for speed and portability.
    1818
    19 The C API is designed in the following way:
     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.
    2021
    2122.. code-block:: C
     
    2425   aubio_foobar_t * new_aubio_foobar(void * args);
    2526   // del_ to delete foobar
    26    void del_aubio_something (aubio_something_t * t);
    27    // _do to process output = foobar(input)
    28    audio_something_do (aubio_something_t * t, fvec_t * input, cvec_t * output);
    29    // _get_param to get foobar.param
    30    smpl_t aubio_something_get_a_parameter (aubio_something_t * t);
    31    // _set_param to set foobar.param
    32    uint_t aubio_something_set_a_parameter (aubio_something_t * t, smpl_t a_parameter);
     27   void del_aubio_foobar (aubio_foobar_t * foobar);
    3328
    34 For performance and real-time operation, no memory allocation or freeing take
    35 place in the `_do` methods. Instead, memory allocation should always take place
    36 in the `new_` methods, whereas free operations are done in the `del_` methods.
    37 
    38 
    39 Vectors and matrix
    40 ------------------
    41 
    42 ``fvec_t`` are used to hold vectors of float (``smpl_t``).
    43 
    44 .. literalinclude:: ../tests/src/test-fvec.c
    45    :language: C
    46    :lines: 7
    47 
     29The main computations are done in the `_do` methods.
    4830
    4931.. code-block:: C
    5032
    51         // set some elements
    52         vec->data[511] = 2.;
    53         vec->data[vec->length-2] = 1.;
     33   // _do to process output = foobar(input)
     34   audio_foobar_do (aubio_foobar_t * foobar, fvec_t * input, cvec_t * output);
    5435
    55 Similarly, ``fmat_t`` are used to hold matrix of floats.
     36Most parameters can be read and written at any time:
    5637
    57 .. literalinclude:: ../tests/src/test-fmat.c
    58    :language: C
    59    :lines: 9-19
     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
    6084
    6185Reading a sound file
Note: See TracChangeset for help on using the changeset viewer.