markdown/additional/design/orc-integration.md

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