libs/ardour/lv2/lv2plug.in/ns/ext/state/state.h

   1 /*
   2   Copyright 2010-2011 David Robillard <http://drobilla.net>
   3   Copyright 2010 Leonard Ritter <paniq@paniq.org>
   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
  20    C API for the LV2 State extension <http://lv2plug.in/ns/ext/state>.
  21 */
  22
  23 #ifndef LV2_STATE_H
  24 #define LV2_STATE_H
  25
  26 #include <stdbool.h>
  27 #include <stddef.h>
  28 #include <stdint.h>
  29
  30 #include "lv2/lv2plug.in/ns/lv2core/lv2.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #define LV2_STATE_URI "http://lv2plug.in/ns/ext/state"
  37
  38 typedef void* LV2_State_Handle;
  39
  40 /**
  41    Flags describing value characteristics.
  42
  43    These flags are used along with the value's type URI to determine how to
  44    (de-)serialise the value data, or whether it is even possible to do so.
  45 */
  46 typedef enum {
  47
  48         /**
  49            Plain Old Data.
  50
  51            Values with this flag contain no references to non-stateent or
  52            non-global resources (e.g. pointers, handles, local paths, etc.). It is
  53            safe to copy POD values with a simple memcpy and store them for use at
  54            any time in the future on a machine with a compatible architecture
  55            (e.g. the same endianness and alignment).
  56
  57            Implementations MUST NOT attempt to copy or serialise a non-POD value if
  58            they do not understand its type (and thus know how to correctly do so).
  59         */
  60         LV2_STATE_IS_POD = 1,
  61
  62         /**
  63            Portable (architecture independent) data.
  64
  65            Values with this flag are in a format that is usable on any
  66            architecture, i.e. if the value is saved on one machine it can safely be
  67            restored on another machine regardless of endianness, alignment, etc.
  68         */
  69         LV2_STATE_IS_PORTABLE = 1 << 1,
  70
  71         /**
  72            Native data.
  73
  74            This flag is used by the host to indicate that the saved data is only
  75            going to be used locally in the currently running process (e.g. for
  76            instance duplication or snapshots), so the plugin should use the most
  77            efficient representation possible and not worry about serialisation
  78            and portability.
  79         */
  80         LV2_STATE_IS_NATIVE = 1 << 2
  81
  82 } LV2_State_Flags;
  83
  84 /**
  85    A host-provided function to store a property.
  86    @param handle Must be the handle passed to LV2_State_Interface.save().
  87    @param key The key (predicate) to store @c value under (URI mapped integer).
  88    @param value Pointer to the value (object) to be stored.
  89    @param size The size of the data at @c value in bytes.
  90    @param type The type of @c value (URI).
  91    @param flags LV2_State_Flags for @c value.
  92    @return 0 on success, otherwise a non-zero error code.
  93
  94    The host passes a callback of this type to LV2_State_Interface.save(). This callback
  95    is called repeatedly by the plugin within LV2_State_Interface.save() to store all
  96    the statements that describe its current state.
  97
  98    The host MAY fail to store a property if the type is not understood and is
  99    not LV2_STATE_IS_POD and/or LV2_STATE_IS_PORTABLE. Implementations are
 100    encouraged to use POD and portable values (e.g. string literals) wherever
 101    possible, and use common types (e.g. types from
 102    http://lv2plug.in/ns/ext/atom) regardless, since hosts are likely to already
 103    contain the necessary implementation.
 104
 105    Note that @c size MUST be > 0, and @c value MUST point to a valid region of
 106    memory @c size bytes long (this is required to make restore unambiguous).
 107
 108    The plugin MUST NOT attempt to use this function outside of the
 109    LV2_State_Interface.restore() context.
 110 */
 111 typedef int (*LV2_State_Store_Function)(LV2_State_Handle handle,
 112                                         uint32_t         key,
 113                                         const void*      value,
 114                                         size_t           size,
 115                                         uint32_t         type,
 116                                         uint32_t         flags);
 117
 118 /**
 119    A host-provided function to retrieve a property.
 120    @param handle Must be the handle passed to
 121    LV2_State_Interface.restore().
 122    @param key The key (predicate) of the property to retrieve (URI).
 123    @param size (Output) If non-NULL, set to the size of the restored value.
 124    @param type (Output) If non-NULL, set to the type of the restored value.
 125    @param flags (Output) If non-NULL, set to the LV2_State_Flags for
 126    the returned value.
 127    @return A pointer to the restored value (object), or NULL if no value
 128    has been stored under @c key.
 129
 130    A callback of this type is passed by the host to
 131    LV2_State_Interface.restore(). This callback is called repeatedly by the
 132    plugin within LV2_State_Interface.restore() to retrieve any properties it
 133    requires to restore its state.
 134
 135    The returned value MUST remain valid until LV2_State_Interface.restore()
 136    returns.
 137
 138    The plugin MUST NOT attempt to use this function, or any value returned from
 139    it, outside of the LV2_State_Interface.restore() context. Returned values
 140    MAY be copied for later use if necessary, assuming the plugin knows how to
 141    do so correctly (e.g. the value is POD, or the plugin understands the type).
 142 */
 143 typedef const void* (*LV2_State_Retrieve_Function)(LV2_State_Handle handle,
 144                                                    uint32_t         key,
 145                                                    size_t*          size,
 146                                                    uint32_t*        type,
 147                                                    uint32_t*        flags);
 148
 149 /**
 150    State Extension Data.
 151
 152    When the plugin's extension_data is called with argument LV2_STATE_URI,
 153    the plugin MUST return an LV2_State structure, which remains valid for the
 154    lifetime of the plugin.
 155
 156    The host can use the contained function pointers to save and restore the
 157    state of a plugin instance at any time (provided the threading restrictions
 158    for the given function are met).
 159
 160    The typical use case is to save the plugin's state when a project is saved,
 161    and to restore the state when a project has been loaded. Other uses are
 162    possible (e.g. cloning plugin instances or taking a snapshot of plugin
 163    state).
 164
 165    Stored data is only guaranteed to be compatible between instances of plugins
 166    with the same URI (i.e. if a change to a plugin would cause a fatal error
 167    when restoring state saved by a previous version of that plugin, the plugin
 168    URI MUST change just as it must when ports change incompatibly). Plugin
 169    authors should consider this possibility, and always store sensible data
 170    with meaningful types to avoid such compatibility issues in the future.
 171 */
 172 typedef struct _LV2_State_Interface {
 173
 174         /**
 175            Save plugin state using a host-provided @c store callback.
 176
 177            @param instance The instance handle of the plugin.
 178            @param store The host-provided store callback.
 179            @param handle An opaque pointer to host data, e.g. the map or
 180            file where the values are to be stored. If @c store is called, this MUST
 181            be passed as its handle parameter.
 182            @param flags Flags describing desires properties of this save.  The
 183            plugin SHOULD use these values to determine the most appropriate and/or
 184            efficient serialisation, but is not required to do so.
 185            @param features Extensible parameter for passing any additional
 186            features to be used for this save.
 187
 188            The plugin is expected to store everything necessary to completely
 189            restore its state later (possibly much later, in a different process, on
 190            a completely different machine, etc.)
 191
 192            The @c handle pointer and @c store function MUST NOT be used
 193            beyond the scope of save().
 194
 195            This function has its own special threading class: it may not be called
 196            concurrently with any "Instantiation" function, but it may be called
 197            concurrently with functions in any other class, unless the definition of
 198            that class prohibits it (e.g. it may not be called concurrently with a
 199            "Discovery" function, but it may be called concurrently with an "Audio"
 200            function. The plugin is responsible for any locking or lock-free
 201            techniques necessary to make this possible.
 202
 203            Note that in the simple case where state is only modified by restore(),
 204            there are no synchronization issues since save() is never called
 205            concurrently with restore() (though run() may read it during a save).
 206
 207            Plugins that dynamically modify state while running, however, must take
 208            care to do so in such a way that a concurrent call to save() will save a
 209            consistent representation of plugin state for a single instant in time.
 210         */
 211         void (*save)(LV2_Handle                 instance,
 212                      LV2_State_Store_Function   store,
 213                      LV2_State_Handle           handle,
 214                      uint32_t                   flags,
 215                      const LV2_Feature *const * features);
 216
 217
 218         /**
 219            Restore plugin state using a host-provided @c retrieve callback.
 220
 221            @param instance The instance handle of the plugin.
 222            @param retrieve The host-provided retrieve callback.
 223            @param handle An opaque pointer to host data, e.g. the map or
 224            file from which the values are to be restored. If @c retrieve is
 225            called, this MUST be passed as its handle parameter.
 226            @param flags Currently unused.
 227            @param features Extensible parameter for passing any additional
 228            features to be used for this restore.
 229
 230            The plugin MAY assume a restored value was set by a previous call to
 231            LV2_State_Interface.save() by a plugin with the same URI.
 232
 233            The plugin MUST gracefully fall back to a default value when a value can
 234            not be retrieved. This allows the host to reset the plugin state with an
 235            empty map.
 236
 237            The @c handle pointer and @c store function MUST NOT be used
 238            beyond the scope of restore().
 239
 240            This function is in the "Instantiation" threading class as defined by
 241            LV2. This means it MUST NOT be called concurrently with any other
 242            function on the same plugin instance.
 243         */
 244         void (*restore)(LV2_Handle                  instance,
 245                         LV2_State_Retrieve_Function retrieve,
 246                         LV2_State_Handle            handle,
 247                         uint32_t                    flags,
 248                         const LV2_Feature *const *  features);
 249
 250 } LV2_State_Interface;
 251
 252 #ifdef __cplusplus
 253 } /* extern "C" */
 254 #endif
 255
 256 #endif /* LV2_STATE_H */