DPF

DISTRHO Plugin Framework
Log | Files | Refs | Submodules | README | LICENSE

lv2_programs.h (6283B)

      1 /*
      2   LV2 Programs Extension
      3   Copyright 2012 Filipe Coelho <falktx@falktx.com>
      4 
      5   Permission to use, copy, modify, and/or distribute this software for any
      6   purpose with or without fee is hereby granted, provided that the above
      7   copyright notice and this permission notice appear in all copies.
      8 
      9   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
     10   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
     11   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
     12   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
     13   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
     14   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
     15   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
     16 */
     17 
     18 /**
     19    @file lv2_programs.h
     20    C header for the LV2 programs extension <http://kxstudio.sf.net/ns/lv2ext/programs>.
     21 */
     22 
     23 #ifndef LV2_PROGRAMS_H
     24 #define LV2_PROGRAMS_H
     25 
     26 #include "lv2.h"
     27 #include "ui.h"
     28 
     29 #define LV2_PROGRAMS_URI    "http://kxstudio.sf.net/ns/lv2ext/programs"
     30 #define LV2_PROGRAMS_PREFIX LV2_PROGRAMS_URI "#"
     31 
     32 #define LV2_PROGRAMS__Host        LV2_PROGRAMS_PREFIX "Host"
     33 #define LV2_PROGRAMS__Interface   LV2_PROGRAMS_PREFIX "Interface"
     34 #define LV2_PROGRAMS__UIInterface LV2_PROGRAMS_PREFIX "UIInterface"
     35 
     36 #ifdef __cplusplus
     37 extern "C" {
     38 #endif
     39 
     40 typedef void* LV2_Programs_Handle;
     41 
     42 typedef struct _LV2_Program_Descriptor {
     43 
     44     /** Bank number for this program. Note that this extension does not
     45         support MIDI-style separation of bank LSB and MSB values. There is
     46         no restriction on the set of available banks: the numbers do not
     47         need to be contiguous, there does not need to be a bank 0, etc. */
     48     uint32_t bank;
     49 
     50     /** Program number (unique within its bank) for this program. There is
     51         no restriction on the set of available programs: the numbers do not
     52         need to be contiguous, there does not need to be a program 0, etc. */
     53     uint32_t program;
     54 
     55     /** Name of the program. */
     56     const char * name;
     57 
     58 } LV2_Program_Descriptor;
     59 
     60 /**
     61    Programs extension, plugin data.
     62 
     63    When the plugin's extension_data is called with argument LV2_PROGRAMS__Interface,
     64    the plugin MUST return an LV2_Programs_Instance structure, which remains valid
     65    for the lifetime of the plugin.
     66 */
     67 typedef struct _LV2_Programs_Interface {
     68     /**
     69      * get_program()
     70      *
     71      * This member is a function pointer that provides a description
     72      * of a program (named preset sound) available on this plugin.
     73      *
     74      * The index argument is an index into the plugin's list of
     75      * programs, not a program number as represented by the Program
     76      * field of the LV2_Program_Descriptor. (This distinction is
     77      * needed to support plugins that use non-contiguous program or
     78      * bank numbers.)
     79      *
     80      * This function returns a LV2_Program_Descriptor pointer that is
     81      * guaranteed to be valid only until the next call to get_program
     82      * or deactivate, on the same plugin instance. This function must
     83      * return NULL if passed an index argument out of range, so that
     84      * the host can use it to query the number of programs as well as
     85      * their properties.
     86      */
     87     const LV2_Program_Descriptor *(*get_program)(LV2_Handle handle,
     88                                                  uint32_t index);
     89 
     90     /**
     91      * select_program()
     92      *
     93      * This member is a function pointer that selects a new program
     94      * for this plugin. The program change should take effect
     95      * immediately at the start of the next run() call. (This
     96      * means that a host providing the capability of changing programs
     97      * between any two notes on a track must vary the block size so as
     98      * to place the program change at the right place. A host that
     99      * wanted to avoid this would probably just instantiate a plugin
    100      * for each program.)
    101      *
    102      * Plugins should ignore a select_program() call with an invalid
    103      * bank or program.
    104      *
    105      * A plugin is not required to select any particular default
    106      * program on activate(): it's the host's duty to set a program
    107      * explicitly.
    108      *
    109      * A plugin is permitted to re-write the values of its input
    110      * control ports when select_program is called. The host should
    111      * re-read the input control port values and update its own
    112      * records appropriately. (This is the only circumstance in which
    113      * a LV2 plugin is allowed to modify its own control-input ports.)
    114      */
    115     void (*select_program)(LV2_Handle handle,
    116                            uint32_t bank,
    117                            uint32_t program);
    118 
    119 } LV2_Programs_Interface;
    120 
    121 /**
    122    Programs extension, UI data.
    123 
    124    When the UI's extension_data is called with argument LV2_PROGRAMS__UIInterface,
    125    the UI MUST return an LV2_Programs_UI_Interface structure, which remains valid
    126    for the lifetime of the UI.
    127 */
    128 typedef struct _LV2_Programs_UI_Interface {
    129     /**
    130      * select_program()
    131      *
    132      * This is exactly the same as select_program in LV2_Programs_Instance,
    133      * but this struct relates to the UI instead of the plugin.
    134      *
    135      * When called, UIs should update their state to match the selected program.
    136      */
    137     void (*select_program)(LV2UI_Handle handle,
    138                            uint32_t bank,
    139                            uint32_t program);
    140 
    141 } LV2_Programs_UI_Interface;
    142 
    143 /**
    144     Feature data for LV2_PROGRAMS__Host.
    145 */
    146 typedef struct _LV2_Programs_Host {
    147     /**
    148      *  Opaque host data.
    149      */
    150     LV2_Programs_Handle handle;
    151 
    152     /**
    153      * program_changed()
    154      *
    155      * Tell the host to reload a plugin's program.
    156      * Parameter handle MUST be the 'handle' member of this struct.
    157      * Parameter index is program index to change.
    158      * When index is -1, host should reload all the programs.
    159      *
    160      * The plugin MUST NEVER call this function on a RT context or during run().
    161      *
    162      * NOTE: This call is to inform the host about a program's bank, program or name change.
    163      *       It DOES NOT change the current selected program.
    164      */
    165     void (*program_changed)(LV2_Programs_Handle handle,
    166                             int32_t index);
    167 
    168 } LV2_Programs_Host;
    169 
    170 #ifdef __cplusplus
    171 } /* extern "C" */
    172 #endif
    173 
    174 #endif /* LV2_PROGRAMS_H */