git.maemo.org Git - mafwsubrenderer/blob - gst-plugins-base-subtitles0.10/docs/design/design-orc-integration.txt

   1
   2 Orc Integration
   3 ===============
   4
   5 Sections
   6 --------
   7
   8  - About Orc
   9  - Fast memcpy()
  10  - Normal Usage
  11  - Build Process
  12  - Testing
  13  - Orc Limitations
  14
  15
  16 About Orc
  17 ---------
  18
  19 Orc code can be in one of two forms: in .orc files that is converted
  20 by orcc to C code that calls liborc functions, or C code that calls
  21 liborc to create complex operations at runtime.  The former is mostly
  22 for functions with predetermined functionality.  The latter is for
  23 functionality that is determined at runtime, where writing .orc
  24 functions for all combinations would be prohibitive.  Orc also has
  25 a fast memcpy and memset which are useful independently.
  26
  27
  28 Fast memcpy()
  29 -------------
  30
  31 *** This part is not integrated yet. ***
  32
  33 Orc has built-in functions orc_memcpy() and orc_memset() that work
  34 like memcpy() and memset().  These are meant for large copies only.
  35 A reasonable cutoff for using orc_memcpy() instead of memcpy() is
  36 if the number of bytes is generally greater than 100.  DO NOT use
  37 orc_memcpy() if the typical is size is less than 20 bytes, especially
  38 if the size is known at compile time, as these cases are inlined by
  39 the compiler.
  40
  41 (Example: sys/ximage/ximagesink.c)
  42
  43 Add $(ORC_CFLAGS) to libgstximagesink_la_CFLAGS and $(ORC_LIBS) to
  44 libgstximagesink_la_LIBADD.  Then, in the source file, add:
  45
  46   #ifdef HAVE_ORC
  47   #include <orc/orc.h>
  48   #else
  49   #define orc_memcpy(a,b,c) memcpy(a,b,c)
  50   #endif
  51
  52 Then switch relevant uses of memcpy() to orc_memcpy().
  53
  54 The above example works whether or not Orc is enabled at compile
  55 time.
  56
  57
  58 Normal Usage
  59 ------------
  60
  61 The following lines are added near the top of Makefile.am for plugins
  62 that use Orc code in .orc files (this is for the volume plugin):
  63
  64   ORC_BASE=volume
  65   include $(top_srcdir)/common/orc.mk
  66
  67 Also add the generated source file to the plugin build:
  68
  69   nodist_libgstvolume_la_SOURCES = $(ORC_SOURCES)
  70
  71 And of course, add $(ORC_CFLAGS) to libgstvolume_la_CFLAGS, and
  72 $(ORC_LIBS) to libgstvolume_la_LIBADD.
  73
  74 The value assigned to ORC_BASE does not need to be related to
  75 the name of the plugin.
  76
  77
  78 Advanced Usage
  79 --------------
  80
  81 The Holy Grail of Orc usage is to programmatically generate Orc code
  82 at runtime, have liborc compile it into binary code at runtime, and
  83 then execute this code.  Currently, the best example of this is in
  84 Schroedinger.  An example of how this would be used is audioconvert:
  85 given an input format, channel position manipulation, dithering and
  86 quantizing configuration, and output format, a Orc code generator
  87 would create an OrcProgram, add the appropriate instructions to do
  88 each step based on the configuration, and then compile the program.
  89 Sucessfully compiling the program would return a function pointer
  90 that can be called to perform the operation.
  91
  92 This sort of advanced usage requires structural changes to current
  93 plugins (e.g., audioconvert) and will probably be developed
  94 incrementally.  Moreover, if such code is intended to be used without
  95 Orc as strict build/runtime requirement, two codepaths would need to
  96 be developed and tested.  For this reason, until GStreamer requires
  97 Orc, I think it's a good idea to restrict such advanced usage to the
  98 cog plugin in -bad, which requires Orc.
  99
 100
 101 Build Process
 102 -------------
 103
 104 The goal of the build process is to make Orc non-essential for most
 105 developers and users.  This is not to say you shouldn't have Orc
 106 installed -- without it, you will get slow backup C code, just that
 107 people compiling GStreamer are not forced to switch from Liboil to
 108 Orc immediately.
 109
 110 With Orc installed, the build process will use the Orc Compiler (orcc)
 111 to convert each .orc file into a temporary C source (tmp-orc.c) and a
 112 temporary header file (${name}orc.h if constructed from ${base}.orc).
 113 The C source file is compiled and linked to the plugin, and the header
 114 file is included by other source files in the plugin.
 115
 116 If 'make orc-update' is run in the source directory, the files
 117 tmp-orc.c and ${base}orc.h are copied to ${base}orc-dist.c and
 118 ${base}orc-dist.h respectively.  The -dist.[ch] files are automatically
 119 disted via orc.mk.  The -dist.[ch] files should be checked in to
 120 git whenever the .orc source is changed and checked in.  Example
 121 workflow:
 122
 123   edit .orc file
 124   ... make, test, etc.
 125   make orc-update
 126   git add volume.orc volumeorc-dist.c volumeorc-dist.h
 127   git commit
 128
 129 At 'make dist' time, all of the .orc files are compiled, and then
 130 copied to their -dist.[ch] counterparts, and then the -dist.[ch]
 131 files are added to the dist directory.
 132
 133 Without Orc installed (or --disable-orc given to configure), the
 134 -dist.[ch] files are copied to tmp-orc.c and ${name}orc.h.  When
 135 compiled Orc disabled, DISABLE_ORC is defined in config.h, and
 136 the C backup code is compiled.  This backup code is pure C, and
 137 does not include orc headers or require linking against liborc.
 138
 139 The common/orc.mk build method is limited by the inflexibility of
 140 automake.  The file tmp-orc.c must be a fixed filename, using ORC_NAME
 141 to generate the filename does not work because it conflicts with
 142 automake's dependency generation.  Building multiple .orc files
 143 is not possible due to this restriction.
 144
 145
 146 Testing
 147 -------
 148
 149 If you create another .orc file, please add it to
 150 tests/orc/Makefile.am.  This causes automatic test code to be
 151 generated and run during 'make check'.  Each function in the .orc
 152 file is tested by comparing the results of executing the run-time
 153 compiled code and the C backup function.
 154
 155
 156 Orc Limitations
 157 ---------------
 158
 159 audioconvert
 160
 161   Orc doesn't have a mechanism for generating random numbers, which
 162   prevents its use as-is for dithering.  One way around this is to
 163   generate suitable dithering values in one pass, then use those
 164   values in a second Orc-based pass.
 165
 166   Orc doesn't handle 64-bit float, for no good reason.
 167
 168   Irrespective of Orc handling 64-bit float, it would be useful to
 169   have a direct 32-bit float to 16-bit integer conversion.
 170
 171   audioconvert is a good candidate for programmatically generated
 172   Orc code.
 173
 174   audioconvert enumerates functions in terms of big-endian vs.
 175   little-endian.  Orc's functions are "native" and "swapped".
 176   Programmatically generating code removes the need to worry about
 177   this.
 178
 179   Orc doesn't handle 24-bit samples.  Fixing this is not a priority
 180   (for ds).
 181
 182 videoscale
 183
 184   Orc doesn't handle horizontal resampling yet.  The plan is to add
 185   special sampling opcodes, for nearest, bilinear, and cubic
 186   interpolation.
 187
 188 videotestsrc
 189
 190   Lots of code in videotestsrc needs to be rewritten to be SIMD
 191   (and Orc) friendly, e.g., stuff that uses oil_splat_u8().
 192
 193   A fast low-quality random number generator in Orc would be useful
 194   here.
 195
 196 volume
 197
 198   Many of the comments on audioconvert apply here as well.
 199
 200   There are a bunch of FIXMEs in here that are due to misapplied
 201   patches.
 202
 203
 204