Changes between Version 1 and Version 2 of API


Ignore:
Timestamp:
Oct 17, 2009, 3:26:39 AM (15 years ago)
Author:
Paul Brossier
Comment:

brain dumping mode, feedback would be nice

Legend:

Unmodified
Added
Removed
Modified
  • API

    v1 v2  
    11= API design =
    22
    3 The API design, as being prepared for aubio 0.4.0, is as follow:
     3The design of each 'object' in aubio is as follows.
    44
     5The private structure, which members are defined in the '.c' source file and not directly accessible from outside this file.
    56
    67{{{
    7 typedef _aubio_foo_t aubio_foo_t;
     8typedef struct _aubio_foo_t aubio_foo_t;
     9}}}
    810
     11The creation function, which should take as little parameters as required, yet be general enough to be flexible. All the memory allocation required for this object should take place in this function.
     12
     13{{{
     14aubio_foo_t * new_aubio_foo (char_t * mode,
     15      uint_t buf_size, uint_t hop_size, uint_t channels, uint_t samplerate);
    916}}}
     17
     18The processing function, should be always be named ''object_name_do''. In general it should take one input and one output, although some exceptions may happen.
     19
     20{{{
     21void aubio_foo_do (aubio_foo_t *o, fvec_t * in, fvec_t * out);
     22}}}
     23
     24The ''setter'' functions, which take one or more arguments, should always return an unsigned int. Unless specified in the documentation, it should be assumed that these functions are not real time, since they could have to do some memory allocation operation, for instance to re-size vectors.
     25
     26{{{
     27uint_t aubio_foo_set_param1 (aubio_foo_t * o, smpl_t param1);
     28uint_t aubio_foo_set_param2 (aubio_foo_t * o, fvec_t * param2);
     29}}}
     30
     31Similarly, ''getter'' functions can be used to get some data or observe about what is going on inside the object.
     32
     33{{{
     34cvec_t * aubio_foo_get_feature1 (aubio_foo_t * bt);
     35smpl_t aubio_foo_get_confidence (aubio_foo_t * bt);
     36}}}
     37
     38Optionally, parameters can have a ''getter'' function. The return type of a getter is same as the type of the parameter to get.
     39
     40{{{
     41smpl_t aubio_foo_get_param1 (aubio_foo_t * bt);
     42}}}
     43
     44The function to destroy the object should take only one argument, this object, and not return anything:
     45
     46{{{
     47void del_aubio_foo(aubio_tempo_t * o);
     48}}}
     49
     50This design should allow for some flexibility without breaking the ABI compatibility. For instance, adding parameters and modifying the object members should be transparent for developers using aubio. The choice of the parameters for the ''new_'' functions are very important. Here are some guidelines about these.
     51
     52 - Unless the object really requires it, do not add an argument to its ''new_'' function.
     53 - If you pass the number of channels, pass it last.
     54 - If it you pass the sampling rate, pass it last, after the number of channels.