Lilv 0.4.4
lilv.h
00001 /*
00002   Copyright 2007-2011 David Robillard <http://drobilla.net>
00003 
00004   Permission to use, copy, modify, and/or distribute this software for any
00005   purpose with or without fee is hereby granted, provided that the above
00006   copyright notice and this permission notice appear in all copies.
00007 
00008   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
00009   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
00010   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
00011   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
00012   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
00013   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
00014   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
00015 */
00016 
00021 #ifndef LILV_LILV_H
00022 #define LILV_LILV_H
00023 
00024 #include <stdbool.h>
00025 #include <stddef.h>
00026 #include <stdint.h>
00027 
00028 #include "lv2/lv2plug.in/ns/lv2core/lv2.h"
00029 
00030 #ifdef LILV_SHARED
00031 #    ifdef __WIN32__
00032 #        define LILV_LIB_IMPORT __declspec(dllimport)
00033 #        define LILV_LIB_EXPORT __declspec(dllexport)
00034 #    else
00035 #        define LILV_LIB_IMPORT __attribute__((visibility("default")))
00036 #        define LILV_LIB_EXPORT __attribute__((visibility("default")))
00037 #    endif
00038 #    ifdef LILV_INTERNAL
00039 #        define LILV_API LILV_LIB_EXPORT
00040 #    else
00041 #        define LILV_API LILV_LIB_IMPORT
00042 #    endif
00043 #else
00044 #    define LILV_API
00045 #endif
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 #define LILV_NS_DOAP "http://usefulinc.com/ns/doap#"
00052 #define LILV_NS_FOAF "http://xmlns.com/foaf/0.1/"
00053 #define LILV_NS_LILV "http://drobilla.net/ns/lilv#"
00054 #define LILV_NS_LV2  "http://lv2plug.in/ns/lv2core#"
00055 #define LILV_NS_RDF  "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
00056 #define LILV_NS_RDFS "http://www.w3.org/2000/01/rdf-schema#"
00057 #define LILV_NS_XSD  "http://www.w3.org/2001/XMLSchema#"
00058 
00059 #define LILV_URI_AUDIO_PORT   "http://lv2plug.in/ns/lv2core#AudioPort"
00060 #define LILV_URI_CONTROL_PORT "http://lv2plug.in/ns/lv2core#ControlPort"
00061 #define LILV_URI_EVENT_PORT   "http://lv2plug.in/ns/ext/event#EventPort"
00062 #define LILV_URI_INPUT_PORT   "http://lv2plug.in/ns/lv2core#InputPort"
00063 #define LILV_URI_MIDI_EVENT   "http://lv2plug.in/ns/ext/midi#MidiEvent"
00064 #define LILV_URI_OUTPUT_PORT  "http://lv2plug.in/ns/lv2core#OutputPort"
00065 #define LILV_URI_PORT         "http://lv2plug.in/ns/lv2core#Port"
00066 
00067 typedef struct LilvPluginImpl      LilvPlugin;       
00068 typedef struct LilvPluginClassImpl LilvPluginClass;  
00069 typedef struct LilvPortImpl        LilvPort;         
00070 typedef struct LilvScalePointImpl  LilvScalePoint;   
00071 typedef struct LilvUIImpl          LilvUI;           
00072 typedef struct LilvNodeImpl        LilvNode;         
00073 typedef struct LilvWorldImpl       LilvWorld;        
00074 typedef struct LilvInstanceImpl    LilvInstance;     
00076 typedef void LilvIter;           
00077 typedef void LilvPluginClasses;  
00078 typedef void LilvPlugins;        
00079 typedef void LilvScalePoints;    
00080 typedef void LilvUIs;            
00081 typedef void LilvNodes;          
00103 LILV_API
00104 const char*
00105 lilv_uri_to_path(const char* uri);
00106 
00111 LILV_API
00112 LilvNode*
00113 lilv_new_uri(LilvWorld* world, const char* uri);
00114 
00119 LILV_API
00120 LilvNode*
00121 lilv_new_string(LilvWorld* world, const char* str);
00122 
00127 LILV_API
00128 LilvNode*
00129 lilv_new_int(LilvWorld* world, int val);
00130 
00135 LILV_API
00136 LilvNode*
00137 lilv_new_float(LilvWorld* world, float val);
00138 
00143 LILV_API
00144 LilvNode*
00145 lilv_new_bool(LilvWorld* world, bool val);
00146 
00151 LILV_API
00152 void
00153 lilv_node_free(LilvNode* val);
00154 
00158 LILV_API
00159 LilvNode*
00160 lilv_node_duplicate(const LilvNode* val);
00161 
00165 LILV_API
00166 bool
00167 lilv_node_equals(const LilvNode* value, const LilvNode* other);
00168 
00182 LILV_API
00183 char*
00184 lilv_node_get_turtle_token(const LilvNode* value);
00185 
00189 LILV_API
00190 bool
00191 lilv_node_is_uri(const LilvNode* value);
00192 
00198 LILV_API
00199 const char*
00200 lilv_node_as_uri(const LilvNode* value);
00201 
00205 LILV_API
00206 bool
00207 lilv_node_is_blank(const LilvNode* value);
00208 
00214 LILV_API
00215 const char*
00216 lilv_node_as_blank(const LilvNode* value);
00217 
00222 LILV_API
00223 bool
00224 lilv_node_is_literal(const LilvNode* value);
00225 
00230 LILV_API
00231 bool
00232 lilv_node_is_string(const LilvNode* value);
00233 
00237 LILV_API
00238 const char*
00239 lilv_node_as_string(const LilvNode* value);
00240 
00244 LILV_API
00245 bool
00246 lilv_node_is_float(const LilvNode* value);
00247 
00253 LILV_API
00254 float
00255 lilv_node_as_float(const LilvNode* value);
00256 
00260 LILV_API
00261 bool
00262 lilv_node_is_int(const LilvNode* value);
00263 
00268 LILV_API
00269 int
00270 lilv_node_as_int(const LilvNode* value);
00271 
00275 LILV_API
00276 bool
00277 lilv_node_is_bool(const LilvNode* value);
00278 
00283 LILV_API
00284 bool
00285 lilv_node_as_bool(const LilvNode* value);
00286 
00308 /* Collections */
00309 
00319 #define LILV_FOREACH(colltype, iter, collection) \
00320     for (LilvIter* (iter) = lilv_ ## colltype ## _begin(collection); \
00321          !lilv_ ## colltype ## _is_end(collection, iter); \
00322          (iter) = lilv_ ## colltype ## _next(collection, iter))
00323 
00324 /* LilvPluginClasses */
00325 
00326 LILV_API
00327 void
00328 lilv_plugin_classes_free(LilvPluginClasses* collection);
00329 
00330 LILV_API
00331 unsigned
00332 lilv_plugin_classes_size(const LilvPluginClasses* collection);
00333 
00334 LILV_API
00335 LilvIter*
00336 lilv_plugin_classes_begin(const LilvPluginClasses* collection);
00337 
00338 LILV_API
00339 const LilvPluginClass*
00340 lilv_plugin_classes_get(const LilvPluginClasses* collection, LilvIter* i);
00341 
00342 LILV_API
00343 LilvIter*
00344 lilv_plugin_classes_next(const LilvPluginClasses* collection, LilvIter* i);
00345 
00346 LILV_API
00347 bool
00348 lilv_plugin_classes_is_end(const LilvPluginClasses* collection, LilvIter* i);
00349 
00356 LILV_API
00357 const LilvPluginClass*
00358 lilv_plugin_classes_get_by_uri(const LilvPluginClasses* classes,
00359                                const LilvNode*          uri);
00360 
00361 /* ScalePoints */
00362 
00363 LILV_API
00364 void
00365 lilv_scale_points_free(LilvScalePoints* collection);
00366 
00367 LILV_API
00368 unsigned
00369 lilv_scale_points_size(const LilvScalePoints* collection);
00370 
00371 LILV_API
00372 LilvIter*
00373 lilv_scale_points_begin(const LilvScalePoints* collection);
00374 
00375 LILV_API
00376 const LilvScalePoint*
00377 lilv_scale_points_get(const LilvScalePoints* collection, LilvIter* i);
00378 
00379 LILV_API
00380 LilvIter*
00381 lilv_scale_points_next(const LilvScalePoints* collection, LilvIter* i);
00382 
00383 LILV_API
00384 bool
00385 lilv_scale_points_is_end(const LilvScalePoints* collection, LilvIter* i);
00386 
00387 /* UIs */
00388 
00389 LILV_API
00390 void
00391 lilv_uis_free(LilvUIs* collection);
00392 
00393 LILV_API
00394 unsigned
00395 lilv_uis_size(const LilvUIs* collection);
00396 
00397 LILV_API
00398 LilvIter*
00399 lilv_uis_begin(const LilvUIs* collection);
00400 
00401 LILV_API
00402 const LilvUI*
00403 lilv_uis_get(const LilvUIs* collection, LilvIter* i);
00404 
00405 LILV_API
00406 LilvIter*
00407 lilv_uis_next(const LilvUIs* collection, LilvIter* i);
00408 
00409 LILV_API
00410 bool
00411 lilv_uis_is_end(const LilvUIs* collection, LilvIter* i);
00412 
00419 LILV_API
00420 const LilvUI*
00421 lilv_uis_get_by_uri(const LilvUIs*  uis,
00422                     const LilvNode* uri);
00423 
00424 /* Nodes */
00425 
00426 LILV_API
00427 void
00428 lilv_nodes_free(LilvNodes* collection);
00429 
00430 LILV_API
00431 unsigned
00432 lilv_nodes_size(const LilvNodes* collection);
00433 
00434 LILV_API
00435 LilvIter*
00436 lilv_nodes_begin(const LilvNodes* collection);
00437 
00438 LILV_API
00439 const LilvNode*
00440 lilv_nodes_get(const LilvNodes* collection, LilvIter* i);
00441 
00442 LILV_API
00443 LilvIter*
00444 lilv_nodes_next(const LilvNodes* collection, LilvIter* i);
00445 
00446 LILV_API
00447 bool
00448 lilv_nodes_is_end(const LilvNodes* collection, LilvIter* i);
00449 
00450 LILV_API
00451 LilvNode*
00452 lilv_nodes_get_first(const LilvNodes* collection);
00453 
00457 LILV_API
00458 bool
00459 lilv_nodes_contains(const LilvNodes* values, const LilvNode* value);
00460 
00461 /* Plugins */
00462 
00463 LILV_API
00464 unsigned
00465 lilv_plugins_size(const LilvPlugins* collection);
00466 
00467 LILV_API
00468 LilvIter*
00469 lilv_plugins_begin(const LilvPlugins* collection);
00470 
00471 LILV_API
00472 const LilvPlugin*
00473 lilv_plugins_get(const LilvPlugins* collection, LilvIter* i);
00474 
00475 LILV_API
00476 LilvIter*
00477 lilv_plugins_next(const LilvPlugins* collection, LilvIter* i);
00478 
00479 LILV_API
00480 bool
00481 lilv_plugins_is_end(const LilvPlugins* collection, LilvIter* i);
00482 
00489 LILV_API
00490 const LilvPlugin*
00491 lilv_plugins_get_by_uri(const LilvPlugins* plugins,
00492                         const LilvNode*    uri);
00493 
00508 LILV_API
00509 LilvWorld*
00510 lilv_world_new(void);
00511 
00519 #define LILV_OPTION_FILTER_LANG "http://drobilla.net/ns/lilv#filter-lang"
00520 
00525 #define LILV_OPTION_DYN_MANIFEST "http://drobilla.net/ns/lilv#dyn-manifest"
00526 
00534 LILV_API
00535 void
00536 lilv_world_set_option(LilvWorld*      world,
00537                       const char*     uri,
00538                       const LilvNode* value);
00539 
00547 LILV_API
00548 void
00549 lilv_world_free(LilvWorld* world);
00550 
00562 LILV_API
00563 void
00564 lilv_world_load_all(LilvWorld* world);
00565 
00578 LILV_API
00579 void
00580 lilv_world_load_bundle(LilvWorld* world,
00581                        LilvNode*  bundle_uri);
00582 
00586 LILV_API
00587 const LilvPluginClass*
00588 lilv_world_get_plugin_class(const LilvWorld* world);
00589 
00594 LILV_API
00595 const LilvPluginClasses*
00596 lilv_world_get_plugin_classes(const LilvWorld* world);
00597 
00609 LILV_API
00610 const LilvPlugins*
00611 lilv_world_get_all_plugins(const LilvWorld* world);
00612 
00618 LILV_API
00619 LilvNodes*
00620 lilv_world_find_nodes(LilvWorld*      world,
00621                       const LilvNode* subject,
00622                       const LilvNode* predicate,
00623                       const LilvNode* object);
00624 
00641 LILV_API
00642 bool
00643 lilv_plugin_verify(const LilvPlugin* plugin);
00644 
00659 LILV_API
00660 const LilvNode*
00661 lilv_plugin_get_uri(const LilvPlugin* plugin);
00662 
00674 LILV_API
00675 const LilvNode*
00676 lilv_plugin_get_bundle_uri(const LilvPlugin* plugin);
00677 
00686 LILV_API
00687 const LilvNodes*
00688 lilv_plugin_get_data_uris(const LilvPlugin* plugin);
00689 
00696 LILV_API
00697 const LilvNode*
00698 lilv_plugin_get_library_uri(const LilvPlugin* plugin);
00699 
00707 LILV_API
00708 LilvNode*
00709 lilv_plugin_get_name(const LilvPlugin* plugin);
00710 
00714 LILV_API
00715 const LilvPluginClass*
00716 lilv_plugin_get_class(const LilvPlugin* plugin);
00717 
00730 LILV_API
00731 LilvNodes*
00732 lilv_plugin_get_value(const LilvPlugin* p,
00733                       const LilvNode*   predicate);
00734 
00740 LILV_API
00741 bool
00742 lilv_plugin_has_feature(const LilvPlugin* p,
00743                         const LilvNode*   feature_uri);
00744 
00755 LILV_API
00756 LilvNodes*
00757 lilv_plugin_get_supported_features(const LilvPlugin* p);
00758 
00770 LILV_API
00771 LilvNodes*
00772 lilv_plugin_get_required_features(const LilvPlugin* p);
00773 
00782 LILV_API
00783 LilvNodes*
00784 lilv_plugin_get_optional_features(const LilvPlugin* p);
00785 
00789 LILV_API
00790 uint32_t
00791 lilv_plugin_get_num_ports(const LilvPlugin* p);
00792 
00807 LILV_API
00808 void
00809 lilv_plugin_get_port_ranges_float(const LilvPlugin* p,
00810                                   float*            min_values,
00811                                   float*            max_values,
00812                                   float*            def_values);
00813 
00820 LILV_API
00821 uint32_t
00822 lilv_plugin_get_num_ports_of_class(const LilvPlugin* p,
00823                                    const LilvNode*   class_1, ...);
00824 
00830 LILV_API
00831 bool
00832 lilv_plugin_has_latency(const LilvPlugin* p);
00833 
00843 LILV_API
00844 uint32_t
00845 lilv_plugin_get_latency_port_index(const LilvPlugin* p);
00846 
00850 LILV_API
00851 const LilvPort*
00852 lilv_plugin_get_port_by_index(const LilvPlugin* plugin,
00853                               uint32_t          index);
00854 
00860 LILV_API
00861 const LilvPort*
00862 lilv_plugin_get_port_by_symbol(const LilvPlugin* plugin,
00863                                const LilvNode*   symbol);
00864 
00870 LILV_API
00871 LilvNode*
00872 lilv_plugin_get_author_name(const LilvPlugin* plugin);
00873 
00879 LILV_API
00880 LilvNode*
00881 lilv_plugin_get_author_email(const LilvPlugin* plugin);
00882 
00888 LILV_API
00889 LilvNode*
00890 lilv_plugin_get_author_homepage(const LilvPlugin* plugin);
00891 
00898 LILV_API
00899 bool
00900 lilv_plugin_is_replaced(const LilvPlugin* plugin);
00901 
00911 LILV_API
00912 LilvNodes*
00913 lilv_port_get_value(const LilvPlugin* plugin,
00914                     const LilvPort*   port,
00915                     const LilvNode*   predicate);
00916 
00920 LILV_API
00921 LilvNodes*
00922 lilv_port_get_properties(const LilvPlugin* plugin,
00923                          const LilvPort*   port);
00924 
00928 LILV_API
00929 bool
00930 lilv_port_has_property(const LilvPlugin* p,
00931                        const LilvPort*   port,
00932                        const LilvNode*   property_uri);
00933 
00937 LILV_API
00938 bool
00939 lilv_port_supports_event(const LilvPlugin* p,
00940                          const LilvPort*   port,
00941                          const LilvNode*   event_uri);
00942 
00948 LILV_API
00949 const LilvNode*
00950 lilv_port_get_symbol(const LilvPlugin* plugin,
00951                      const LilvPort*   port);
00952 
00959 LILV_API
00960 LilvNode*
00961 lilv_port_get_name(const LilvPlugin* plugin,
00962                    const LilvPort*   port);
00963 
00971 LILV_API
00972 const LilvNodes*
00973 lilv_port_get_classes(const LilvPlugin* plugin,
00974                       const LilvPort*   port);
00975 
00984 LILV_API
00985 bool
00986 lilv_port_is_a(const LilvPlugin* plugin,
00987                const LilvPort*   port,
00988                const LilvNode*   port_class);
00989 
00998 LILV_API
00999 void
01000 lilv_port_get_range(const LilvPlugin* plugin,
01001                     const LilvPort*   port,
01002                     LilvNode**        deflt,
01003                     LilvNode**        min,
01004                     LilvNode**        max);
01005 
01013 LILV_API
01014 LilvScalePoints*
01015 lilv_port_get_scale_points(const LilvPlugin* plugin,
01016                            const LilvPort*   port);
01017 
01028 LILV_API
01029 const LilvNode*
01030 lilv_scale_point_get_label(const LilvScalePoint* point);
01031 
01036 LILV_API
01037 const LilvNode*
01038 lilv_scale_point_get_value(const LilvScalePoint* point);
01039 
01051 LILV_API
01052 const LilvNode*
01053 lilv_plugin_class_get_parent_uri(const LilvPluginClass* plugin_class);
01054 
01059 LILV_API
01060 const LilvNode*
01061 lilv_plugin_class_get_uri(const LilvPluginClass* plugin_class);
01062 
01067 LILV_API
01068 const LilvNode*
01069 lilv_plugin_class_get_label(const LilvPluginClass* plugin_class);
01070 
01075 LILV_API
01076 LilvPluginClasses*
01077 lilv_plugin_class_get_children(const LilvPluginClass* plugin_class);
01078 
01089 /* Instance of a plugin.
01090    This is exposed in the ABI to allow inlining of performance critical
01091    functions like lilv_instance_run (simple wrappers of functions in lv2.h).
01092    This is for performance reasons, user code should not use this definition
01093    in any way (which is why it is not machine documented).
01094    Truly private implementation details are hidden via @a ref pimpl.
01095 */
01096 struct LilvInstanceImpl {
01097     const LV2_Descriptor* lv2_descriptor;
01098     LV2_Handle            lv2_handle;
01099     void*                 pimpl;
01100 };
01101 
01115 LILV_API
01116 LilvInstance*
01117 lilv_plugin_instantiate(const LilvPlugin*        plugin,
01118                         double                   sample_rate,
01119                         const LV2_Feature*const* features);
01120 
01126 LILV_API
01127 void
01128 lilv_instance_free(LilvInstance* instance);
01129 
01130 #ifndef LILV_INTERNAL
01131 
01136 static inline const char*
01137 lilv_instance_get_uri(const LilvInstance* instance)
01138 {
01139     return instance->lv2_descriptor->URI;
01140 }
01141 
01147 static inline void
01148 lilv_instance_connect_port(LilvInstance* instance,
01149                            uint32_t      port_index,
01150                            void*         data_location)
01151 {
01152     instance->lv2_descriptor->connect_port
01153         (instance->lv2_handle, port_index, data_location);
01154 }
01155 
01162 static inline void
01163 lilv_instance_activate(LilvInstance* instance)
01164 {
01165     if (instance->lv2_descriptor->activate)
01166         instance->lv2_descriptor->activate(instance->lv2_handle);
01167 }
01168 
01174 static inline void
01175 lilv_instance_run(LilvInstance* instance,
01176                   uint32_t      sample_count)
01177 {
01178     instance->lv2_descriptor->run(instance->lv2_handle, sample_count);
01179 }
01180 
01186 static inline void
01187 lilv_instance_deactivate(LilvInstance* instance)
01188 {
01189     if (instance->lv2_descriptor->deactivate)
01190         instance->lv2_descriptor->deactivate(instance->lv2_handle);
01191 }
01192 
01198 static inline const void*
01199 lilv_instance_get_extension_data(const LilvInstance* instance,
01200                                  const char*         uri)
01201 {
01202     if (instance->lv2_descriptor->extension_data)
01203         return instance->lv2_descriptor->extension_data(uri);
01204     else
01205         return NULL;
01206 }
01207 
01215 static inline const LV2_Descriptor*
01216 lilv_instance_get_descriptor(const LilvInstance* instance)
01217 {
01218     return instance->lv2_descriptor;
01219 }
01220 
01228 static inline LV2_Handle
01229 lilv_instance_get_handle(const LilvInstance* instance)
01230 {
01231     return instance->lv2_handle;
01232 }
01233 
01234 #endif /* LILV_INTERNAL */
01235 
01246 LILV_API
01247 LilvUIs*
01248 lilv_plugin_get_uis(const LilvPlugin* plugin);
01249 
01255 LILV_API
01256 const LilvNode*
01257 lilv_ui_get_uri(const LilvUI* ui);
01258 
01267 LILV_API
01268 const LilvNodes*
01269 lilv_ui_get_classes(const LilvUI* ui);
01270 
01276 LILV_API
01277 bool
01278 lilv_ui_is_a(const LilvUI* ui, const LilvNode* class_uri);
01279 
01286 typedef unsigned (*LilvUISupportedFunc)(const char* container_type_uri,
01287                                         const char* ui_type_uri);
01288 
01298 LILV_API
01299 unsigned
01300 lilv_ui_is_supported(const LilvUI*       ui,
01301                      LilvUISupportedFunc supported_func,
01302                      const LilvNode*     container_type,
01303                      const LilvNode**    ui_type);
01304 
01310 LILV_API
01311 const LilvNode*
01312 lilv_ui_get_bundle_uri(const LilvUI* ui);
01313 
01319 LILV_API
01320 const LilvNode*
01321 lilv_ui_get_binary_uri(const LilvUI* ui);
01322 
01328 #ifdef __cplusplus
01329 } /* extern "C" */
01330 #endif
01331 
01332 #endif /* LILV_LILV_H */