This directory contains the source code needed to build Csound
extensions into the Loris library. These extensions enable the (shared)
Loris library to be dynamically loaded into Csound using the
--opcode-lib flag, as in

  csound --opcode-lib=/usr/local/lib/libloris.so test.csd

You will need, in addition to Loris, a copy of the Csound source code
(extensions need to include a header that is part of the Csound source
code). The Loris configure script will attempt to automatically detect
the presence of Csound and the requisite header file, and build the
opcodes into the Loris. If the header cannot be found, the Csound
generators are not incorporated into the Loris library.

There are two csd files in this directory that demonstrate the Loris
opcodes. Please read them before running them, since they depend on SDIF
files generated elsewhere.

------------------------------------------------------------------------

Adding Loris to Csound 4:

If you are still using Csound 4, then you can try replacing the
lorisgens5 files in the src directory with the lorisgens4 files. This
code is no longer tested or supported.

The remainder of this document describes the method for adding the Loris
generators to Csound 4 by rebuilding the csound program from source code.
This method of extending Csound is deprecated in favor of dynamic opcode 
modules, and is no longer tested or supported. 

The Loris unit generators rely on improvements to the Csound extension
API (such as deinitialization routines and support for modules written
in C++) unavailable in early Csound versions, so before you begin, make
sure that your version of the Csound source is newer than version 4.17.
Version 4.18 seems to work fine. Also, of course, make sure that you can
build csound from your copy of the source before you attempt to add the
new Loris modules.

Adding lorisgens to Csound:

Step 1: Introduce the Loris unit generators into entry1.c or entry2.c:

a) Add
  
  #include "lorisgens4.h" 

to the list of headers included at top of file.

b) Add declarations for the functions invoked directly by the Loris unit
generators:

void lorisread_setup(void*);  
void lorisread(void*);
void lorisplay_setup(void*);
void lorisplay(void*);
void lorismorph_setup(void*);
void lorismorph(void*);

must be added to the list of function definitions found after all the
#include statements.


c) Add the Loris unit generator to the opcode list by adding:

{"lorisread",  S(LORISREAD),  3, "",  "kSikkko", lorisread_setup,  lorisread, NULL },
{"lorisplay",  S(LORISPLAY),  5, "a", "ikkk",    lorisplay_setup,  NULL, lorisplay },
{"lorismorph", S(LORISMORPH), 3, "",  "iiikkk",  lorismorph_setup, lorismorph, NULL }
 
to the array of similar OENTRY structures.


Step 2: Modify the Makefile (there are several, make sure to modify the
one you use in your csound build!) to compile and link the Loris unit
generator source, and to link in the loris library.

a) Add the Loris unit generator source code to the list of sources:

LORISSRC = lorisgens4.C

and add $(LORISSRC) to list of sources CSRCS.

b) Add the Loris unit generator object file to the list of objects used
to link the csound binary:

LORISOBJ = lorisgens4.o

and add $(LORISOBJ) to list of objects COBJS.

c) Add the Loris unit generator header to the list of headers by adding
lorisgens4.h to list of headers HDRS.

d) Add the Loris C++ headers path (usually /usr/local/include/loris, but
depending on the prefix you used when building Loris) to the header
search path. This can be accomplished by adding something like

  -I/usr/local/include/loris

(substituting the correct path if necessary) to the definition of CFLAGS.

e) Add the loris library to the list of libraries LIBS. This can be accomplished
by adding 

  -lloris
  
to the definition of LIBS. If you have used a nonstandard prefix, say /opt, for building the
Loris library, you may also need to add something like 

  -L/opt/lib
  
to the LIB definition.

You may also need to add

	-lstdc++

to the LIB definition to include the standard C++ library (it may
have a different name if you are not using a GNU C/C++ compiler).

f) Finally, add a rule for compiling c++ source files. The following should do:

.C.o:
	$(CXX) $(CFLAGS) -c $*.C


Step 3: Build and install csound, and start enjoying the Loris unit generators. 
