trunk/doc/mainpage.dox

/**

@mainpage libgig


@section Intro

libgig is a C++ library for accessing audio-sample based instrument files,
as they are shipped for various software samplers, hardware sampler devices
and synthesizer keyboards.
This C++ library was originally created to access Gigasampler files, but in the
meantime grew to much more than that. At the moment libgig consists of the
following four major parts:

  - @b 1. @ref gig classes: These provide convenient access to
    @b Gigasampler / @b GigaStudio files (for all known format version, that is
    from Gigasampler v1 to GigaStudio v4), allowing to load, modify and save
    existing .gig files, as well as creating new .gig files from scratch.<br>
    <br>
    Since the gig file format was originally designed based on the DLS Level 2
    format, the gig classes in this library are derived from the DLS classes of
    this library, where the gig classes provide the necessary extensions for the
    Gigasampler file format.<br>
    <br>
    Besides the fact that libgig supports all aspects of the original
    Gigasampler / GigaStudio format, it now also provides some own extensions of
    that original format. Most notably libgig provides an extension to save
    @ref gig::Script "real-time instrument scripts" with .gig files.
    Those custom extensions are
    however currently only supported by the graphical instrument editor
    application @b gigedit and by @b LinuxSampler, those extensions will
    obviously not work with the original GigaStudio software.

  - @b 2. @ref sf2 classes: These provide support for loading and modifying
    @b SoundFont version 2 files. Even though being an older format, the
    SoundFont format is still one of the most popular sample based instrument
    file formats and is widely supported by a variety of hardware and software.

  - @b 3. @ref Korg classes: These provide support for loading sample based
    instrument files of KORG's synthesizer keyboard models <i>Kronos</i>,
    <i>M3</i>, <i>Oasys</i>, <i>Triton</i> and <i>Trinity</i>. There is
    currently no support for modifying KORG files yet.

  - @b 4. @b AKAI classes: These provide support for loading sample based disks
    (CDROMs, hard disks, ZIP disks) and disk image files of AKAI's hardware
    sampler series <i>S1000</i>, <i>S01</i>, <i>S2000</i> and <i>S3000</i>.<br>
    <br>
    The AKAI classes are a branch of <i>libakai</i>. In the AKAI classes of
    libgig, libakai's original dependency to the so called <i>Carbon</i> C++
    library has been removed and has been replaced by using ordinay
    <a href="http://en.wikipedia.org/wiki/Standard_Template_Library">C++ STL</a>
    classes instead. Further, this branch of libakai also provides support for
    Linux and other POSIX based OSes (the original libakai was limited to Mac
    and Windows).<br>
    <br>
    Currently the AKAI classes don't have their own dedicated C++ namespace.
    Refer to class @ref AkaiDisk as toplevel entry class for accessing AKAI
    sounds.

Besides the mentioned major parts above, libgig also provides the following
three other components:

  - @b 5. @ref DLS classes: Provide convenient methods to access
    @b DLS (<i>Downloadable Sounds</i>) Level 1 and 2 files. The DLS file format
    has been designed as open file format to be adopted by various keyboard
    manufacturers for their sounds. However it never really made it to a broad
    standard. You can use the DLS classes of libgig to load, modify and create
    DLS files from scratch, however you will probably not find many DLS files
    and/or software or hardware that supports this file format. The main reason
    why these classes exist in libgig, is because of the fact that the
    Gigasampler / GigaStudio file format was designed as extension on top of the
    DLS file format (with quite some radical modifications though).

  - @b 6. @ref RIFF classes: Provide convenient methods to parse and access
    arbitrary RIFF files. The <i>"Resource Interchange File Format"</i>
    provides universal data containers ordered in a tree-like structure
    and can be compared to XML, but with the difference that RIFF is
    binary encoded.<br>
    <br>
    The DLS file format, the gig file format, the sf2 file format and KORG's
    file format are all based on RIFF on lowest level of their file format. And
    consequently all those classes mentioned above are using the RIFF classes
    for that purpose.

  - @b 7. @ref Serialization classes: This is a separate framework on its own,
    which allows efficient and powerful serialization and deserialization of
    native C++ objects and is used by @ref gig classes and i.e. the gigedit
    application for implementing a preset system.


@section License

Most parts of libgig and its tools are released under the terms of the
<a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License (GPL)</a>.
This applies to the @ref gig classes, @ref sf2 classes, @ref Korg classes, @ref DLS classes,
@ref RIFF classes and all of their tools and example programs. We may offer you a
commercial license for using libgig in commercial products. If you are
interested in a commercial license,
<a href="http://www.linuxsampler.org/developers.html">contact us!</a>

The @b AKAI classes and their tools / example programs are released under the terms
of the <a href="https://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License (LGPL)</a>.

If you have any questions regarding license aspects,
<a href="http://www.linuxsampler.org/developers.html">contact us!</a>


@section Examples

Beside the actual C++ library, there are the following example applications
which demonstrate how to use the library:

  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gigdump.cpp?view=markup">@b gigdump: </a>
    Prints out the content of a .gig file.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gigextract.cpp?view=markup">@b gigextract: </a>
    Extracts audio samples from a .gig file as .wav files.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gigmerge.cpp?view=markup">@b gigmerge: </a>
    Combines multiple .gig files to one .gig file.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gig2mono.cpp?view=markup">@b gig2mono: </a>
    Converts .gig files from stereo to mono.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gig2stereo.cpp?view=markup">@b gig2stereo: </a>
    Converts .gig files from mono sample pairs to true interleaved stereo.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/dlsdump.cpp?view=markup">@b dlsdump: </a>
    Prints out the content of a DLS file.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/rifftree.cpp?view=markup">@b rifftree: </a>
    Prints out the RIFF tree of an arbitrary RIFF container file.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/sf2dump.cpp?view=markup">@b sf2dump: </a>
    Prints out the content of a .sf2 file.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/sf2extract.cpp?view=markup">@b sf2extract: </a>
    Extracts audio samples from a .sf2 file as .wav files.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/korgdump.cpp?view=markup">@b korgdump: </a>
    Prints out the content of KORG sound files (.KSF, .KMP).
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/korg2gig.cpp?view=markup">@b korg2gig: </a>
    Converts KORG (.KSF, .KMP) sound files to GigaStudio (.gig) files.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/akaidump.cpp?view=markup">@b akaidump: </a>
    Dump an AKAI media i.e. from a CDROM drive as disk image file to your HD.
  - <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/akaiextract.cpp?view=markup">@b akaiextract: </a>
    Extracts audio samples from an AKAI media or from an AKAI disk image file (as .wav files).

Currently libgig ist most prominently used by LinuxSampler and gigedit.


@section Portability

This library is developed and optimized for POSIX compliant operating
systems like Linux and Mac OS X, as well as for Windows. It is written as cross
platform C++ library, so libgig should also compile for other operation systems
as well. Due to this it works on all architectures (i.e. 32 bit x86, 64 bit x86,
PPC and many more). It works on
<a href="http://en.wikipedia.org/wiki/Endianness">little endian and big endian</a>
systems.


@section Bugs

Please report bugs on http://bugs.linuxsampler.org/ and/or subscribe to the
<a href="http://lists.sourceforge.net/lists/listinfo/linuxsampler-devel">LinuxSampler developers mailing list</a>.

@section Outro

For compilation instructions, requirements and further details please refer
to the README file et al.

That's all folks. Happy hacking!

 -- Christian Schoenebeck <cuse@users.sourceforge.net>

@see http://www.linuxsampler.org

*/
1	schoenebeck	1378	/**
2
3			@mainpage libgig
4
5
6			@section Intro
7
8	schoenebeck	2650	libgig is a C++ library for accessing audio-sample based instrument files,
9	schoenebeck	2652	as they are shipped for various software samplers, hardware sampler devices
10			and synthesizer keyboards.
11	schoenebeck	2650	This C++ library was originally created to access Gigasampler files, but in the
12			meantime grew to much more than that. At the moment libgig consists of the
13	schoenebeck	2652	following four major parts:
14	schoenebeck	1378
15	schoenebeck	2650	- @b 1. @ref gig classes: These provide convenient access to
16			@b Gigasampler / @b GigaStudio files (for all known format version, that is
17			from Gigasampler v1 to GigaStudio v4), allowing to load, modify and save
18	schoenebeck	2651	existing .gig files, as well as creating new .gig files from scratch.<br>
19			<br>
20	schoenebeck	2650	Since the gig file format was originally designed based on the DLS Level 2
21			format, the gig classes in this library are derived from the DLS classes of
22			this library, where the gig classes provide the necessary extensions for the
23	schoenebeck	2651	Gigasampler file format.<br>
24			<br>
25	schoenebeck	2650	Besides the fact that libgig supports all aspects of the original
26			Gigasampler / GigaStudio format, it now also provides some own extensions of
27			that original format. Most notably libgig provides an extension to save
28	schoenebeck	2652	@ref gig::Script "real-time instrument scripts" with .gig files.
29			Those custom extensions are
30	schoenebeck	2650	however currently only supported by the graphical instrument editor
31	schoenebeck	2652	application @b gigedit and by @b LinuxSampler, those extensions will
32			obviously not work with the original GigaStudio software.
33	schoenebeck	1378
34	schoenebeck	2652	- @b 2. @ref sf2 classes: These provide support for loading and modifying
35			@b SoundFont version 2 files. Even though being an older format, the
36			SoundFont format is still one of the most popular sample based instrument
37			file formats and is widely supported by a variety of hardware and software.
38
39			- @b 3. @ref Korg classes: These provide support for loading sample based
40			instrument files of KORG's synthesizer keyboard models <i>Kronos</i>,
41	schoenebeck	2650	<i>M3</i>, <i>Oasys</i>, <i>Triton</i> and <i>Trinity</i>. There is
42			currently no support for modifying KORG files yet.
43	schoenebeck	1378
44	schoenebeck	2652	- @b 4. @b AKAI classes: These provide support for loading sample based disks
45	schoenebeck	2650	(CDROMs, hard disks, ZIP disks) and disk image files of AKAI's hardware
46	schoenebeck	2651	sampler series <i>S1000</i>, <i>S01</i>, <i>S2000</i> and <i>S3000</i>.<br>
47			<br>
48	schoenebeck	2650	The AKAI classes are a branch of <i>libakai</i>. In the AKAI classes of
49			libgig, libakai's original dependency to the so called <i>Carbon</i> C++
50			library has been removed and has been replaced by using ordinay
51			<a href="http://en.wikipedia.org/wiki/Standard_Template_Library">C++ STL</a>
52			classes instead. Further, this branch of libakai also provides support for
53			Linux and other POSIX based OSes (the original libakai was limited to Mac
54	schoenebeck	2651	and Windows).<br>
55			<br>
56	schoenebeck	2650	Currently the AKAI classes don't have their own dedicated C++ namespace.
57			Refer to class @ref AkaiDisk as toplevel entry class for accessing AKAI
58			sounds.
59
60			Besides the mentioned major parts above, libgig also provides the following
61	schoenebeck	3183	three other components:
62	schoenebeck	2650
63	schoenebeck	2652	- @b 5. @ref DLS classes: Provide convenient methods to access
64	schoenebeck	2650	@b DLS (<i>Downloadable Sounds</i>) Level 1 and 2 files. The DLS file format
65			has been designed as open file format to be adopted by various keyboard
66			manufacturers for their sounds. However it never really made it to a broad
67			standard. You can use the DLS classes of libgig to load, modify and create
68			DLS files from scratch, however you will probably not find many DLS files
69			and/or software or hardware that supports this file format. The main reason
70			why these classes exist in libgig, is because of the fact that the
71			Gigasampler / GigaStudio file format was designed as extension on top of the
72			DLS file format (with quite some radical modifications though).
73
74	schoenebeck	2652	- @b 6. @ref RIFF classes: Provide convenient methods to parse and access
75			arbitrary RIFF files. The <i>"Resource Interchange File Format"</i>
76	schoenebeck	2650	provides universal data containers ordered in a tree-like structure
77			and can be compared to XML, but with the difference that RIFF is
78	schoenebeck	2651	binary encoded.<br>
79			<br>
80	schoenebeck	2652	The DLS file format, the gig file format, the sf2 file format and KORG's
81			file format are all based on RIFF on lowest level of their file format. And
82			consequently all those classes mentioned above are using the RIFF classes
83			for that purpose.
84	schoenebeck	2650
85	schoenebeck	3183	- @b 7. @ref Serialization classes: This is a separate framework on its own,
86			which allows efficient and powerful serialization and deserialization of
87			native C++ objects and is used by @ref gig classes and i.e. the gigedit
88			application for implementing a preset system.
89	schoenebeck	2650
90	schoenebeck	3183
91	schoenebeck	1378	@section License
92
93	schoenebeck	2650	Most parts of libgig and its tools are released under the terms of the
94			<a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License (GPL)</a>.
95	schoenebeck	2652	This applies to the @ref gig classes, @ref sf2 classes, @ref Korg classes, @ref DLS classes,
96			@ref RIFF classes and all of their tools and example programs. We may offer you a
97	schoenebeck	2650	commercial license for using libgig in commercial products. If you are
98			interested in a commercial license,
99			<a href="http://www.linuxsampler.org/developers.html">contact us!</a>
100	schoenebeck	1378
101	schoenebeck	2652	The @b AKAI classes and their tools / example programs are released under the terms
102	schoenebeck	2650	of the <a href="https://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License (LGPL)</a>.
103	schoenebeck	1378
104	schoenebeck	2650	If you have any questions regarding license aspects,
105			<a href="http://www.linuxsampler.org/developers.html">contact us!</a>
106
107
108	schoenebeck	1378	@section Examples
109
110	schoenebeck	2650	Beside the actual C++ library, there are the following example applications
111			which demonstrate how to use the library:
112	schoenebeck	1378
113	schoenebeck	2650	- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gigdump.cpp?view=markup">@b gigdump: </a>
114			Prints out the content of a .gig file.
115			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gigextract.cpp?view=markup">@b gigextract: </a>
116			Extracts audio samples from a .gig file as .wav files.
117			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gigmerge.cpp?view=markup">@b gigmerge: </a>
118			Combines multiple .gig files to one .gig file.
119			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gig2mono.cpp?view=markup">@b gig2mono: </a>
120			Converts .gig files from stereo to mono.
121	schoenebeck	2805	- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/gig2stereo.cpp?view=markup">@b gig2stereo: </a>
122			Converts .gig files from mono sample pairs to true interleaved stereo.
123	schoenebeck	2650	- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/dlsdump.cpp?view=markup">@b dlsdump: </a>
124			Prints out the content of a DLS file.
125			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/rifftree.cpp?view=markup">@b rifftree: </a>
126			Prints out the RIFF tree of an arbitrary RIFF container file.
127			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/sf2dump.cpp?view=markup">@b sf2dump: </a>
128			Prints out the content of a .sf2 file.
129	schoenebeck	2805	- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/sf2extract.cpp?view=markup">@b sf2extract: </a>
130			Extracts audio samples from a .sf2 file as .wav files.
131	schoenebeck	2650	- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/korgdump.cpp?view=markup">@b korgdump: </a>
132			Prints out the content of KORG sound files (.KSF, .KMP).
133			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/korg2gig.cpp?view=markup">@b korg2gig: </a>
134			Converts KORG (.KSF, .KMP) sound files to GigaStudio (.gig) files.
135			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/akaidump.cpp?view=markup">@b akaidump: </a>
136			Dump an AKAI media i.e. from a CDROM drive as disk image file to your HD.
137			- <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/libgig/trunk/src/tools/akaiextract.cpp?view=markup">@b akaiextract: </a>
138			Extracts audio samples from an AKAI media or from an AKAI disk image file (as .wav files).
139	schoenebeck	1378
140	schoenebeck	2650	Currently libgig ist most prominently used by LinuxSampler and gigedit.
141	schoenebeck	1378
142
143			@section Portability
144
145			This library is developed and optimized for POSIX compliant operating
146	schoenebeck	2650	systems like Linux and Mac OS X, as well as for Windows. It is written as cross
147			platform C++ library, so libgig should also compile for other operation systems
148			as well. Due to this it works on all architectures (i.e. 32 bit x86, 64 bit x86,
149			PPC and many more). It works on
150			<a href="http://en.wikipedia.org/wiki/Endianness">little endian and big endian</a>
151			systems.
152	schoenebeck	1378
153
154	schoenebeck	2650	@section Bugs
155
156			Please report bugs on http://bugs.linuxsampler.org/ and/or subscribe to the
157			<a href="http://lists.sourceforge.net/lists/listinfo/linuxsampler-devel">LinuxSampler developers mailing list</a>.
158
159	schoenebeck	1378	@section Outro
160
161			For compilation instructions, requirements and further details please refer
162			to the README file et al.
163
164			That's all folks. Happy hacking!
165
166			-- Christian Schoenebeck <cuse@users.sourceforge.net>
167
168			@see http://www.linuxsampler.org
169
170			*/