docs/design/design-orc-integration.txt

Orc Integration
===============

Sections
--------

 - About Orc
 - Fast memcpy()
 - Normal Usage
 - Build Process
 - Testing
 - Orc Limitations


About Orc
---------

Orc code can be in one of two forms: in .orc files that is converted
by orcc to C code that calls liborc functions, or C code that calls
liborc to create complex operations at runtime.  The former is mostly
for functions with predetermined functionality.  The latter is for
functionality that is determined at runtime, where writing .orc
functions for all combinations would be prohibitive.  Orc also has
a fast memcpy and memset which are useful independently.


Fast memcpy()
-------------

*** This part is not integrated yet. ***

Orc has built-in functions orc_memcpy() and orc_memset() that work
like memcpy() and memset().  These are meant for large copies only.
A reasonable cutoff for using orc_memcpy() instead of memcpy() is
if the number of bytes is generally greater than 100.  DO NOT use
orc_memcpy() if the typical is size is less than 20 bytes, especially
if the size is known at compile time, as these cases are inlined by
the compiler.

(Example: sys/ximage/ximagesink.c)

Add $(ORC_CFLAGS) to libgstximagesink_la_CFLAGS and $(ORC_LIBS) to
libgstximagesink_la_LIBADD.  Then, in the source file, add:

  #ifdef HAVE_ORC
  #include <orc/orc.h>
  #else
  #define orc_memcpy(a,b,c) memcpy(a,b,c)
  #endif

Then switch relevant uses of memcpy() to orc_memcpy().

The above example works whether or not Orc is enabled at compile
time.


Normal Usage
------------

The following lines are added near the top of Makefile.am for plugins
that use Orc code in .orc files (this is for the volume plugin):

  ORC_BASE=volume
  include $(top_srcdir)/common/orc.mk

Also add the generated source file to the plugin build:

  nodist_libgstvolume_la_SOURCES = $(ORC_SOURCES)

And of course, add $(ORC_CFLAGS) to libgstvolume_la_CFLAGS, and
$(ORC_LIBS) to libgstvolume_la_LIBADD.

The value assigned to ORC_BASE does not need to be related to
the name of the plugin.


Advanced Usage
--------------

The Holy Grail of Orc usage is to programmatically generate Orc code
at runtime, have liborc compile it into binary code at runtime, and
then execute this code.  Currently, the best example of this is in
Schroedinger.  An example of how this would be used is audioconvert:
given an input format, channel position manipulation, dithering and
quantizing configuration, and output format, a Orc code generator
would create an OrcProgram, add the appropriate instructions to do
each step based on the configuration, and then compile the program.
Successfully compiling the program would return a function pointer
that can be called to perform the operation.

This sort of advanced usage requires structural changes to current
plugins (e.g., audioconvert) and will probably be developed
incrementally.  Moreover, if such code is intended to be used without
Orc as strict build/runtime requirement, two codepaths would need to
be developed and tested.  For this reason, until GStreamer requires
Orc, I think it's a good idea to restrict such advanced usage to the
cog plugin in -bad, which requires Orc.


Build Process
-------------

The goal of the build process is to make Orc non-essential for most
developers and users.  This is not to say you shouldn't have Orc
installed -- without it, you will get slow backup C code, just that
people compiling GStreamer are not forced to switch from Liboil to
Orc immediately.

With Orc installed, the build process will use the Orc Compiler (orcc)
to convert each .orc file into a temporary C source (tmp-orc.c) and a
temporary header file (${name}orc.h if constructed from ${base}.orc).
The C source file is compiled and linked to the plugin, and the header
file is included by other source files in the plugin.

If 'make orc-update' is run in the source directory, the files
tmp-orc.c and ${base}orc.h are copied to ${base}orc-dist.c and
${base}orc-dist.h respectively.  The -dist.[ch] files are automatically
disted via orc.mk.  The -dist.[ch] files should be checked in to
git whenever the .orc source is changed and checked in.  Example
workflow:

  edit .orc file
  ... make, test, etc.
  make orc-update
  git add volume.orc volumeorc-dist.c volumeorc-dist.h
  git commit

At 'make dist' time, all of the .orc files are compiled, and then
copied to their -dist.[ch] counterparts, and then the -dist.[ch]
files are added to the dist directory.

Without Orc installed (or --disable-orc given to configure), the
-dist.[ch] files are copied to tmp-orc.c and ${name}orc.h.  When
compiled Orc disabled, DISABLE_ORC is defined in config.h, and
the C backup code is compiled.  This backup code is pure C, and
does not include orc headers or require linking against liborc.

The common/orc.mk build method is limited by the inflexibility of
automake.  The file tmp-orc.c must be a fixed filename, using ORC_NAME
to generate the filename does not work because it conflicts with
automake's dependency generation.  Building multiple .orc files
is not possible due to this restriction.


Testing
-------

If you create another .orc file, please add it to
tests/orc/Makefile.am.  This causes automatic test code to be
generated and run during 'make check'.  Each function in the .orc
file is tested by comparing the results of executing the run-time
compiled code and the C backup function.


Orc Limitations
---------------

audioconvert

  Orc doesn't have a mechanism for generating random numbers, which
  prevents its use as-is for dithering.  One way around this is to
  generate suitable dithering values in one pass, then use those
  values in a second Orc-based pass.

  Orc doesn't handle 64-bit float, for no good reason.

  Irrespective of Orc handling 64-bit float, it would be useful to
  have a direct 32-bit float to 16-bit integer conversion.

  audioconvert is a good candidate for programmatically generated
  Orc code.

  audioconvert enumerates functions in terms of big-endian vs.
  little-endian.  Orc's functions are "native" and "swapped".
  Programmatically generating code removes the need to worry about
  this.

  Orc doesn't handle 24-bit samples.  Fixing this is not a priority
  (for ds).

videoscale

  Orc doesn't handle horizontal resampling yet.  The plan is to add
  special sampling opcodes, for nearest, bilinear, and cubic
  interpolation.

videotestsrc

  Lots of code in videotestsrc needs to be rewritten to be SIMD
  (and Orc) friendly, e.g., stuff that uses oil_splat_u8().

  A fast low-quality random number generator in Orc would be useful
  here.

volume
  
  Many of the comments on audioconvert apply here as well.

  There are a bunch of FIXMEs in here that are due to misapplied
  patches.