git.sesse.net Git - mlt/blob - mlt++/README

   1 MLT++
   2 -----
   3
   4         This mlt sub-project provides a C++ wrapping for the MLT library.
   5
   6 INSTALLATION
   7 ------------
   8
   9         ./configure [ --prefix=path ]
  10         make
  11         make install
  12
  13 USAGE
  14 -----
  15
  16         Use the following definitions in a Makefile to compile and link with mlt++:
  17
  18                 CXXFLAGS=`pkg-config --cflags mlt-framework` -Wall
  19                 LDFLAGS=-lmlt++ `pkg-config --libs mlt-framework`
  20
  21         Include files for the classes can either be explicitly included, ie:
  22
  23                 #include <mlt++/MltProducer.h>
  24                 etc
  25
  26         Or you can include all using:
  27
  28                 #include <mlt++/Mlt.h>
  29
  30         All definitions are placed in an Mlt namespace, and adhere closely to the C
  31         naming convention. Mappings always follow the pattern:
  32
  33         Factory methods:
  34
  35                 mlt_factory_init        ==> Mlt::Factory::init
  36                 mlt_factory_producer    ==> Mlt::Factory::producer
  37                 mlt_factory_filter      ==> Mlt::Factory::filter
  38                 mlt_factory_transition  ==> Mlt::Factory::transition
  39                 mlt_factory_consumer    ==> Mlt::Factory::consumer
  40                 mlt_factory_close       ==> Mlt::Factory::close
  41
  42         NB: Factory usage for service construction is optional.
  43
  44         Types:
  45
  46                 mlt_properties          ==> Mlt::Properties
  47                 mlt_frame               ==> Mlt::Frame
  48                 mlt_service             ==> Mlt::Service
  49                 mlt_producer            ==> Mlt::Producer
  50                 mlt_filter              ==> Mlt::Filter
  51                 mlt_transition          ==> Mlt::Transition
  52                 mlt_consumer            ==> Mlt::Consumer
  53
  54         Methods:
  55
  56                 mlt_type_method         ==> Mlt::Type.method
  57         ie:     mlt_playlist_append     ==> Mlt::Playlist.append
  58
  59         Parent methods are available directly on children.
  60
  61         Additionally, you can specify:
  62
  63                 using namespace Mlt;
  64
  65         To avoid the enforced use of the Mlt:: prefix.
  66
  67         Enumerators and macros are reused directly from the C library.
  68
  69 CLASS HIERARCHY
  70 ---------------
  71
  72         The currently mapped objects are shown in the following hierarchy:
  73
  74                 Factory
  75                 Properties
  76                         Frame
  77                         Service
  78                                 Consumer
  79                                 Field
  80                                 Filter
  81                                 Multitrack
  82                                 Producer
  83                                         Playlist
  84                                 Tractor
  85                                 Transition
  86
  87         An additional set of classes allow apps to behave as, and communicate with,
  88         client/server components - these components provide MLT with unique
  89         possibilties for process to process or system to system communications.
  90
  91                 Miracle
  92                 Response
  93
  94 SPECIAL CASES
  95 -------------
  96
  97         Care should be taken with wrapper objects.
  98
  99         Taking, as an example, the C function that returns the immediate consumer of
 100         a service:
 101
 102                 mlt_service mlt_service_consumer( mlt_service );
 103
 104         This maps to:
 105
 106                 Mlt::Service *Mlt::Service.consumer( );
 107
 108         Note that you get an object back - it is never the original c++ object, but
 109         a wrapping object. This is done to keep consistency with the C api which may
 110         instantiate C instances - therefore it cannot be assumed that a C++ object
 111         exists for all mlt service instances.
 112
 113         As such, it is mandatory that you delete these objects. The original will
 114         not be affected. However, all other modifications (to properties or its
 115         state of connection) will be reflected in the original object.
 116
 117         This approach excludes the use of RTTI to determine the real type of the
 118         object - this can only be done by parsing the objects properties.
 119
 120         Objects may be invalid - always use the is_valid method to check validity
 121         before use.
 122
 123 LIMITATIONS
 124 -----------
 125
 126         The mechanisms for the definition of new services are deliberately
 127         excluded from the C++ wrappings - this is done to ensure that service
 128         networks constructed can be serialised and used by existing applications
 129         which are based on the C API (such as miracle).
 130
 131 SWIG
 132 ----
 133
 134         Experimental swig bindings based on mlt++ are provided.
 135