MorphOS Library - User contributions [en]

Exec Lists

2013-01-12T20:26:40Z

Krashan: /* List Iterator */ Fixed bugs in ForEachNode() macro iterator.

''Grzegorz Kraszewski''

=Introduction=
A list is the simplest dynamic data structure. An array is even simplier, but it is not dynamic. Adding a single item to an array requires reallocation of memory and copying the whole old contents, similarly for removing. Inserting and removing elements to a list is very fast operation and its computational costs do not increase with number of items. Because of this, list is the basic structure used in ''exec.library'', the MorphOS kernel. One could say the Exec is built on lists. Lists are also used through all the system to manage processes, windows, screens, devices, DOS volumes, fonts, libraries and more. Of course lists are also used by applications to manage dynamic data. Many more sophisticated data structures are built on lists. For all these reasons understanding lists and their MorphOS flavour is essential for every programmer.

Lists may be divided to intrusive and nonintrusive ones. An intrusive list is one requiring that every list item contains a part called a node. The node is then used for linking items into list. A nonintrusive list creates nodes itself. Both kinds have their advantages. Exec lists are intrusive. Why? For a nonintrusive list adding an item means allocating memory for its node. Exec lists are often used at really low levels of the system, like interrupt handling, process scheduler or input/output hardware devices. Calling memory allocator from there is unacceptable. Also error handling would become a nightmare (every memory allocation can fail...). In some parts of the system lists also have to be extremely fast. Memory allocation is a complex operation and can't be expected to finish in a few processor cycles. Of course on higher levels of the system, intrusiveness has more disadvantages than advantages. For example an item of intrusive list cannot be added to more than one list. Then high level components (for example MUI List class) may be nonintrusive ones.

=From a Plain List to Exec List=
The simplest form of list is a unidirectional one. Node of every item consists only of pointer to the next element. The list is identified by keeping a pointer to its first item. Unidirectional lists however are used only in special cases. While inserting an element at list start is easy, inserting at end requires traversing the whole list. Time of this operation increases linearly with number of items. It is also not possible to traverse the list in the backward direction. Then bidirectional lists are much more common. Exec lists are bidirectional. Every node contains two pointers: one to the next element and one to the previous element. For the first element pointer to the previous one is ''NULL''. For the last one, pointer to the next one is ''NULL''. If a list user keeps pointers to both the first and the last element, she has symmetrical access to the start and the end of the list.

[[File:execlists1.png|center]]

<center>''A plain, bidirectional list. A node consists of "prev" and "next" pointers.''</center>

While the idea is still simple, we have to complicate it a bit. As mentioned before, the list user keeps track of it by maintaining two pointers: to the first and the last item. These pointers will be modified every time an item is added or removed at the start or end of the list respectively. But what if a list has multiple users not knowing about each other? Adding an item at the start or at the end would require pointer update for '''all''' the users. To solve the problem, two artificial items are introduced: a '''list head''' and a '''list tail'''. Those two elements do not carry payload, only consist of a node. Their location does not change during the list lifetime so they work as anchors. Inserting an element at list start is in fact inserting it between the list head and the former first element. Similarly element inserted at end is in fact inserted between the former last element and the list tail. As pointers to the head and the tail are constant, they may be shared between multiple users.

[[File:execlists2.png|center]]

<center>''Bidirectional list with head and tail pseudoitems.''</center>

Exec lists combine the list head and the list tail into one structure, named '''list header'''. As the Exec was designed in the days when computer memory was counted in kilobytes rather than gigabytes, designers saw a way to save a few bytes. The "previous" field of list head node always contains ''NULL''. Similarly the "next" field of the list tail always contains ''NULL''. Then they can be merged into one. That is why the list header contains only three pointers instead of four. For the C language the list header is defined as ''struct List'' and lists are commonly referenced by a pointer to it.

[[File:execlists3.png|center]]

<center>''The Exec list. Head and tail pseudoelements are merged into the list header.''</center>

=Exec List Elements: Node and Header=
Exec defines two kinds of nodes: a full one and a minimal one. The minimal node consists only of pointers to the next and the previous item and is defined in C in ''<exec/nodes.h>'' header file as follows:

struct MinNode
{
struct MinNode *mln_Succ; // successor, the next item
struct MinNode *mln_Pred; // predecessor, the previous item
};

The full node has additional fields used in many system lists. These fields are: item '''name''', item '''type''' and item '''priority'''.

struct Node
{
struct Node* ln_Succ; // successor
struct Node* ln_Pred; // predecessor
UBYTE ln_Type; // item type
BYTE ln_Pri; // item priority
char* ln_Name; // item name
};

Additional node fields have meaning only for system lists and may be considered as part of payload. If we ignore C types, a ''Node'' is just a ''MinNode'' with three fields added at the end. Node priority may be used to implement ordered lists or queues. ''Exec.library'' provides functions for ordered item insertion.

As there are two kinds of nodes, there are also two types of list headers. Both are defined in ''<exec/lists.h>'':

struct MinList
{
struct MinNode* mlh_Head; // pointer to the first real item
struct MinNode* mlh_Tail; // merged head "previous" and tail "next"
struct MinNode* mlh_TailPred; // pointer to the last real item
};

Header for full nodes has additional '''type''' field (used for system lists) and one byte padding to make the structure size even.

struct List
{
struct Node* lh_Head; // pointer to the first real item
struct Node* lh_Tail; // merged head "previous" and tail "next"
struct Node* lh_TailPred; // pointer to the last real item
UBYTE lh_Type;
UBYTE lh_pad;
};

Again, when one ignores C types, the ''List'' structure is ''MinList'' with two extra fields.

As Exec lists are intrusive, a custom item structure must contain ''MinNode'' (or ''Node'' if needed) as the first field. It must be a complete structure, not a pointer. Here is an example:

struct MyNode
{
struct MinNode Node; // must be the first
struct Whatever Foobar; // example payload fields
ULONG Something;
char MoreData[10];
/* ... */
};

There is no limit on custom item size. As items are not copied, big items are manipulated with exactly the same speed as small ones.

=List Initialization, Empty List Check=
The list header, which is either ''List'' or ''MinList'' structure must be initialized before use. Please note well:

----
<center>'''Clearing ''List'' to all zeros is NOT a proper Exec list initialization!'''</center>
----

Looking at the diagrams above, we know how an empty list should look like:

[[File:Execlists4.png|center]]

An empty list contains only its head and tail, both merged into the header. When one splits them back in mind, initialization becomes obvious:
* The "next" field of the head points to the tail.
* The "prev" field of the head is ''NULL''.
* The "next" field of the tail is ''NULL''.
* The "prev" field of the tail points to the head.
Then the second and the third operation merge into one, as fields are merged. Following code performs proper Exec list initialization. Note the address operators '''&''', forgetting them is a common mistake:

struct MinList mylist;

mylist.mlh_Head = (struct MinNode*)'''&'''mylist.mlh_Tail;
mylist.mlh_Tail = NULL;
mylist.mlh_TailPred = (struct MinNode*)'''&'''mylist.mlh_Head;

In case of full ''List'', initialization is the same, just typecasts have ''Node'' instead of ''MinNode''. List initialization is a common operation, so ''<exec/lists.h>'' defines a ''NEWLIST'' macro for it. The macro takes a pointer to ''List'' or ''MinList'', so for the above example it would be called as follows:

NEWLIST(&mylist);

Empty list check is another common operation. It may be derived from the diagram above. One can check if a list is empty using four equivalent conditions:

if (mylist.mlh_Head->mln_Succ == NULL) /* list is empty */
if (mylist.mlh_Head == (struct MinNode*)&mylist.mlh_Tail) /* list is empty */
if (mylist.mlh_TailPred->mln_Pred == NULL) /* list is empty */
if (mylist.mlh_TailPred == (struct MinNode*)&mylist.mlh_Head) /* list is empty */

A ''IsListEmpty()'' macro defined in ''<exec/lists.h>'' uses the last condition, simplified by the fact that address of ''mlh_Head'' is the same as address of the whole ''MinList'' (a good compiler will optimize field reference out anyway).

=List Iterator=

A list iterator is a fragment of code (usually a loop) used for traversing the list and performing operations on its elements. The simplest, browsing iterator is usually implemented as a ''for'' loop:

struct MyNode *n;
struct MinList *list; // let's assume it is initialized already

for (n = (struct MyNode*)list->mlh_Head; n->Node.mln_Succ; n = (struct MyNode*)n->Node.mln_Succ)
{
/* do something with node 'n' */
}

The first part of the ''for'' statement initializes the pointer ''n'' to the first real item of the list (the successor of the head item). The second part is the loop end condition. Loop ends when successor of the current element is ''NULL'', which happens when the current element is the list tail. Then the loop contents is not executed for the tail, as the tail is not a "real" item, as said above. Finally the third part of ''for'' statement moves the pointer to the next list item. A symmetric iterator may be written for browsing a list from the end in backward direction:

for (n = (struct MyNode*)list->mlh_TailPred; n->Node.mln_Pred; n = (struct MyNode*)n->
Node.mln_Pred)
{
/* do something with node 'n' */
}

This time the pointer ''n'' is initialized to the last real item (predecessor of the list tail), pointer is moved to the previous item in each loop turn. The loop finishes, when the predecessor of the current item is ''NULL'', which is the case for the list head. Again, the loop is not executed for the list head itself.

The ''<exec/lists.h>'' header file provides ''ForeachNode()'' macro for building a ''for'' based iterator. The macro is a bit dangerous however, because it blindly typecasts the node pointer to ''struct Node*'' and the list pointer to ''struct List*''. It effectively bypasses the static C language type control and can lead to bugs in code. It is much safer to cast the node pointer to the real type of the list item, as shown in the above example iterators. Then a safer iterator macro should take the type name as one of arguments:

#define ForEachNode(n, T, list) for (n = (T)(list)->mlh_Head; n->Node.mln_Succ; \
n = (T)n->Node.mln_Succ)

The macro may be used as follows:

ForEachNode(n, struct MyNode*, list)
{
/* do something with node 'n' */
}

This macro is not so universal, as it assumes ''MinList'' list and also assumes that the ''MinNode'' field placed at the start of ''MyNode'' structure is named ''Node''. On the other hand it puts static type control in good use. A similar macro may be defined for a backward iterator. In C++ language Exec lists iterators may be defined as templates.

===Removing List Items From Inside of an Iterator===

Some attention has to be put to a case when iterator is used for selective removal of items. Someone may try to do it as follows:

'''/* BAD CODE EXAMPLE */'''

ForEachNode(n, MyNode, list)
{
if (/*some condition*/)
{
Remove((struct Node*)n);
FreeVec(n);
}
}

Why the code above is buggy? If the item ''n'' is being removed and its memory freed, reference to ''n'' in the next loop turn is in fact a reference to free memory. In most cases the memory contents will stay unchanged. That is why such a bug is so popular, it may go unnoticed if the code is not tested enough. Nothing stops the process scheduler to switch our process out, then the memory may be allocated by another process and its contents overwritten. Then, when control will be returned to our process, ''n'' points to undefined data and the loop crashes. A solution of this problem is to read the successor from an item '''before''' the item is freed. It requires a second pointer to be defined:

struct MyNode *n, *n2;

for (n = (struct MyNode*)list->mlh_Head; n2 = (struct MyNode*)n->Node.mln_Succ; n = n2)
{
if (/* some condition */)
{
Remove((struct Node*)n);
FreeVec(n);
}
}

Now a pointer to the successor of item ''n'' is stored in ''n2'' before the item ''n'' is freed. At the next loop turn, the iterator moves
to the next item and checks for the list end using valid ''n2'' pointer instead of a reference to free memory.

Things are easier when all items on the list are to be removed unconditionally, so the list is made empty and all the items are disposed. Of course one can still use the safe loop above, but there is a bit faster alternative:

while (n = (struct MyNode*)RemHead((struct List*)list)) FreeVec(n);

''RemTail()'' function may be used in this loop as well, because when one removes all the items, the order does not matter usually.

=Adding and Removing Items=
Adding an item in arbitrary position of a list requires only updating 4 pointers, regardless of the item size. The diagram below explains the operation.

<center>[[File:Execlists5.png]]<br>
''Inserting an item into an Exec list.''</center>

The diagam corresponds to the following code:

struct MyNode *n; /* insert after this item */
struct MyNode *a; /* insert this */

n->Node.mln_Succ->mln_Pred = &a.Node; /* 1 */
a->Node.mln_Succ = n->Node.mln_Succ; /* 2 */
a->Node.mln_Pred = &n.Node; /* 3 */
n->Node.mln_Succ = &a.Node; /* 4 */

Observe the order of operations. It is important. If one starts from operation 4 for example, he would loose the only link to the rest of the list after the insert position.

Removing link is even faster, as it only requires modifying two pointers: one in the predecessor of removed item and one in its successor. Let's assume element ''n'' is to be removed:

n->Node.mln_Pred->mln_Succ = n->Node.mln_Succ;
n->Node.mln_Succ->mln_Pred = n->Node.mln_Pred;

Insert and remove operations have been standarizded in MorphOS in two ways: as ''exec.library'' API calls and as macros. The library functions are ''Insert()'' and ''Remove()'', their macro counterparts are named ''INSERT()'' and ''REMOVE()''. Both ''Insert()'' function and ''INSERT()'' macro take also a pointer to list header. While it is not neccesary in general case, it allows to handle the case when an item is inserted as the first one by passing ''NULL'' as the insert position. Inserting as the first element can be also done by passing the list header address as the insert position.

It should be noted, that both ''Remove()'' function and ''REMOVE()'' macro '''do not verify''' if the removed node is really in any list. Any attempt to "remove" a node not being in a list may result in random memory trashing and horrible crash.

==Head and Tail==

The most common operations of inserting and removing elements are performed on both the ends of a list. For example common data structures like stack or queue may be implemented using list. For stack, items are added at the list head and also removed from the head. For queue items are added at the tail and removed at the head.

Having a list head and tail pseudoitems gives an advantage, that operations at both list ends are not different than the general case. One just replaces – on the diagram in the previous subchapter – either the element before the insert position with the list head, or the element after the insert position with the list tail. The only difference comes from the fact that head and tail operations usually take just the address of the list header as their argument. The complete set of four operations is provided:
* ''AddHead()'' function and ''ADDHEAD()'' macro add a node as the first one.
* ''RemHead()'' function and ''REMHEAD()'' macro remove the first node and return its address.
* ''AddTail()'' function and ''ADDTAIL()'' macro add a node as the last one.
* ''RemTail()'' function and ''REMTAIL()'' macro remove the last node and return its address.
All these operations require only an address of the list header. Remove operations return the address of removed node, or ''NULL'' if the list is empty.

==Functions or Macros?==

After reading all the sections above it is clear, that most of the list operations is very simple and compiles to a few processor instructions. That is why they are also defined as macros. What to to use then? In general macros are faster, but some of them may be a few bytes longer than calls to library functions (especially ''INSERT()''). On the other hand even a few kilobytes of additional code is usually not a problem nowadays, while gain in speed is often valuable. Then in places where speed is critical, macros are a better choice.

==Enqueueing==

Full list nodes have a '''priority''' field, named ''ln_Pri''. The field is often used by the system to maintain prioritized lists or queues. To keep the list ordered by priority, a special insert operation is required. It is provided as an ''exec.library'' call named ''Enqueue()''. The function takes a node (it must be full ''Node'', not ''MinNode''), reads its priority and finds a place for insert comparing priorities of nodes. If there are any nodes in the list with the same priority as the inserted one, it is inserted '''before''' already existing ones. Of course ''Enqueue()'' may be used also for implementing custom queues. One has to take into account however that the priority field is limited to signed 8-bit number and the function does not scale well for very long lists, as the insert position search is linear.

Installation of Software Development Kit and its basic usage

2013-01-09T17:47:40Z

Krashan: /* Installing the SDK */ Note about Scribble in SDK 3.2 and later.

''Grzegorz Kraszewski''
----
<small>This page in other languages: [[Instalacja SDK (Software Development Kit) i podstawy jego używania|polski]]</small>

==Installing the SDK==

The official MorphOS SDK provides a complete environment for creating programs
for MorphOS. It contains the following components:

* MorphOS includes (for the MorphOS native API).
* Standard C and C++ library includes.
* MorphOS API documentation and example code.
* Two GCC compilers, 2.95.3 and 4.4.5.
* GCC toolchains (one for each compiler), sets of developer utility programs.
* ''Scribble'', an advanced programmer's editor with syntax highlighting and powerful autocomplete and code analyser/hinter feature (starting from SDK 3.2 ''Scribble'' has been moved to the base system).
* Perl scripting language (used by some SDK tools).

The first step of installation is to download the SDK archive from the [http://www.morphos.net morphos.net] site, or by clicking this [http://www.morphos-team.net/files/sdk-20110916.lha direct link]. The SDK is delivered as a LhA archive, which must be depacked before proceeding. The easiest way is to open a context menu for the archive (with the right mouse button in an Ambient window) and choose ''Extract''. After depacking a directory named ''morphossdk'' is created with an ''Installer'' application and a big file named ''sdk.pack'' inside. Installation is started by running ''Installer''. The only user choice that is needed here is to choose an installation directory. Then there is some time spent watching the progress bar...

After the installation a system reboot may be needed to update system assigns and paths.

==Choosing a Compiler==

As mentioned above, the SDK delivers two GCC compilers: an old but trusty 2.95.3 one, and the modern 4.4.5. There is a tool named ''GCCSelect'' in the SDK, which allows for fast switching between compilers. Just type in a shell window

<tt>GCCSelect 2.95.3</tt>

or

<tt>GCCSelect 4.4.5</tt>

to change the current compiler. ''GCCSelect'' works by making symbolic links to the proper version of GCC and its tools, so the compiler is always called as ''gcc'' or ''g++'', regardless of the version chosen currently.

Which one to choose? It depends on the code compiled and other constrains. Here is some guidance:

* 2.95.3 compiles faster and consumes less memory.
* For old code 2.95.3 would be better, as GCC 4 will produce tons of warnings or even errors on code being flawlessly compiled by the old GCC.
* For new projects, especially written in C++, GCC 4 is recommended, as the old one simply does not keep up with modern standards.
* GCC 4 usually produces faster code (but sometimes also bigger, depending on optimizer options).
* GCC 4 is a relatively new and complex compiler, may contain more bugs than 2.95.3.

My general advice is to use GCC 4 and only switch to GCC 2 if needed.

One can check which compiler is currently active using the '''−v''' compiler option, which displays the compiler version and build options:

<tt>gcc -v</tt>

The last line of output shows the GCC version.

==Standard C and C++ Libraries==

These standard libraries are parts of the C and C++ language specifications respectively. They mainly deliver file and console input/output functions, mathematic functions and string operations. The C++ library also provides a set of basic container classes.

* [http://en.wikipedia.org/wiki/C_standard_library C standard library on Wikipedia]
* [http://en.wikipedia.org/wiki/C%2B%2B_Standard_Library C++ standard library on Wikipedia]

There are two ways to access these libraries on MorphOS. The first (and default) one is by using a MorphOS [[MorphOS_API_and_Its_Organization|shared library]]; ''ixemul.library''. As the name suggests, this library tries to provide some Unix environment emulation on MorphOS, which, other than the standard libraries, includes large part of [http://en.wikipedia.org/wiki/Posix POSIX] standard and some other commonly used functions. ''ixemul.library'' is usually used for porting big projects from the Unix/Linux world, for example it is used by GCC itself and many other tools in the SDK.

The second way is to use ''libnix'' (as in; '''''lib''' '''n'''o '''ix'''emul''). In contrast to ''ixemul.library'', ''libnix'' is statically linked with the application. This is the preferred way for providing standard libraries for MorphOS native applications. It is achieved by passing the '''−noixemul''' flag to the compiler and the linker. ''libnix'' delivers full C and C++ standard libraries, but its POSIX implementation is less complete.

<small>Another alternative is to not use standard libraries at all. It may sound crazy at first, but the MorphOS native API provides complete file and console I/O as well as some string manipulation functions and many mathematic functions. Using the native API makes applications faster and smaller in size. On the other hand code using the MorphOS API directly is not portable to non-Amiga(like) systems. A '''−nostdlib''' compiler option instructs the compiler to not link the code with the standard library. Note that this requires also writing your own [[Writing Custom Startup Code|custom startup code]].</small>

Installation of Software Development Kit and its basic usage

2013-01-09T17:46:09Z

Krashan: /* Standard C and C++ Libraries */ Linked to "Writing Custom Startup Code"

''Grzegorz Kraszewski''
----
<small>This page in other languages: [[Instalacja SDK (Software Development Kit) i podstawy jego używania|polski]]</small>

==Installing the SDK==

The official MorphOS SDK provides a complete environment for creating programs
for MorphOS. It contains the following components:

* MorphOS includes (for the MorphOS native API).
* Standard C and C++ library includes.
* MorphOS API documentation and example code.
* Two GCC compilers, 2.95.3 and 4.4.5.
* GCC toolchains (one for each compiler), sets of developer utility programs.
* ''Scribble'', an advanced programmer's editor with syntax highlighting and powerful autocomplete and code analyser/hinter feature.
* Perl scripting language (used by some SDK tools).

The first step of installation is to download the SDK archive from the [http://www.morphos.net morphos.net] site, or by clicking this [http://www.morphos-team.net/files/sdk-20110916.lha direct link]. The SDK is delivered as a LhA archive, which must be depacked before proceeding. The easiest way is to open a context menu for the archive (with the right mouse button in an Ambient window) and choose ''Extract''. After depacking a directory named ''morphossdk'' is created with an ''Installer'' application and a big file named ''sdk.pack'' inside. Installation is started by running ''Installer''. The only user choice that is needed here is to choose an installation directory. Then there is some time spent watching the progress bar...

After the installation a system reboot may be needed to update system assigns and paths.

==Choosing a Compiler==

As mentioned above, the SDK delivers two GCC compilers: an old but trusty 2.95.3 one, and the modern 4.4.5. There is a tool named ''GCCSelect'' in the SDK, which allows for fast switching between compilers. Just type in a shell window

<tt>GCCSelect 2.95.3</tt>

or

<tt>GCCSelect 4.4.5</tt>

to change the current compiler. ''GCCSelect'' works by making symbolic links to the proper version of GCC and its tools, so the compiler is always called as ''gcc'' or ''g++'', regardless of the version chosen currently.

Which one to choose? It depends on the code compiled and other constrains. Here is some guidance:

* 2.95.3 compiles faster and consumes less memory.
* For old code 2.95.3 would be better, as GCC 4 will produce tons of warnings or even errors on code being flawlessly compiled by the old GCC.
* For new projects, especially written in C++, GCC 4 is recommended, as the old one simply does not keep up with modern standards.
* GCC 4 usually produces faster code (but sometimes also bigger, depending on optimizer options).
* GCC 4 is a relatively new and complex compiler, may contain more bugs than 2.95.3.

My general advice is to use GCC 4 and only switch to GCC 2 if needed.

One can check which compiler is currently active using the '''−v''' compiler option, which displays the compiler version and build options:

<tt>gcc -v</tt>

The last line of output shows the GCC version.

==Standard C and C++ Libraries==

These standard libraries are parts of the C and C++ language specifications respectively. They mainly deliver file and console input/output functions, mathematic functions and string operations. The C++ library also provides a set of basic container classes.

* [http://en.wikipedia.org/wiki/C_standard_library C standard library on Wikipedia]
* [http://en.wikipedia.org/wiki/C%2B%2B_Standard_Library C++ standard library on Wikipedia]

There are two ways to access these libraries on MorphOS. The first (and default) one is by using a MorphOS [[MorphOS_API_and_Its_Organization|shared library]]; ''ixemul.library''. As the name suggests, this library tries to provide some Unix environment emulation on MorphOS, which, other than the standard libraries, includes large part of [http://en.wikipedia.org/wiki/Posix POSIX] standard and some other commonly used functions. ''ixemul.library'' is usually used for porting big projects from the Unix/Linux world, for example it is used by GCC itself and many other tools in the SDK.

The second way is to use ''libnix'' (as in; '''''lib''' '''n'''o '''ix'''emul''). In contrast to ''ixemul.library'', ''libnix'' is statically linked with the application. This is the preferred way for providing standard libraries for MorphOS native applications. It is achieved by passing the '''−noixemul''' flag to the compiler and the linker. ''libnix'' delivers full C and C++ standard libraries, but its POSIX implementation is less complete.

<small>Another alternative is to not use standard libraries at all. It may sound crazy at first, but the MorphOS native API provides complete file and console I/O as well as some string manipulation functions and many mathematic functions. Using the native API makes applications faster and smaller in size. On the other hand code using the MorphOS API directly is not portable to non-Amiga(like) systems. A '''−nostdlib''' compiler option instructs the compiler to not link the code with the standard library. Note that this requires also writing your own [[Writing Custom Startup Code|custom startup code]].</small>

Writing Custom Startup Code

2012-12-29T15:43:34Z

Krashan: /* Reasons for Writing Own Startup */ small bug

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a signal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([[Installation of Software Development Kit and its basic usage#Standard C and C++ Libraries|more on this]]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When the program is linked with ''libnix'', the possibility of using own startup depends on the standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should use '''−nostdlib''' option, which also implies '''−nostartfiles'''.

=Let's Write It=

Before we start to write the code, note that except things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (the one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()'' function. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. The GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note it is time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts with including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase;
struct Library *DOSBase;

As our code will use these two libaries, we need to define their bases.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, the executable will be recognized as PowerUP one and executed through ''ppc.library'', with unpredictable results.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from the ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns the calling task's own descriptor if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'' function, if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' may fail for other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what does ''Forbid()'' do here? This function halts system multitasking, specifically it prevents the system process scheduler to switch our process away. Usually it may be done for a very short period of time only and followed by a matching ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when the process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies the Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but the version string is usually placed in it, so I've decided to write a few words about it. The version string is a short text in some defined format. This string contains the program name, version and revision number, compilation date and optionally copyrigth or author info. The version string is decoded by many applications including Ambient, the system command ''version'', the Installer program and more. The text starts with '''$VER:''', so it can be easily found in the program executable. As version tools search for the version string from the start of the executable file, it is best if version string is placed as close to the beginning of the file as possible. If the version string is declared as a simple string constant, it is unfortunately placed in one of the ELF data sections. These sections are placed after the code section by the linker. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into the ELF section named ''.text'', which is the code section. As the startup code object is linked as the first object, the version string will appear at the beginning of the executable, just after the code of the ''Start()'' function. Why after? It is simple, if we place it before the real code, the operating system will jump "into" the string, trying to execute it, and then of course it will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows the described ideas at work. It only uses the MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T13:48:58Z

Krashan: /* Let's Write It */ __abox__ proper explanation

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a signal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([[Installation of Software Development Kit and its basic usage#Standard C and C++ Libraries|more on this]]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When the program is linked with ''libnix'', the possibility of using own startup depends on the standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should use '''−nostdlib''' option, which also implies '''−nostdlib'''.

=Let's Write It=

Before we start to write the code, note that except things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (the one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()'' function. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. The GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note it is time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts with including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase;
struct Library *DOSBase;

As our code will use these two libaries, we need to define their bases.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, the executable will be recognized as PowerUP one and executed through ''ppc.library'', with unpredictable results.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from the ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns the calling task's own descriptor if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'' function, if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' may fail for other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what does ''Forbid()'' do here? This function halts system multitasking, specifically it prevents the system process scheduler to switch our process away. Usually it may be done for a very short period of time only and followed by a matching ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when the process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies the Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but the version string is usually placed in it, so I've decided to write a few words about it. The version string is a short text in some defined format. This string contains the program name, version and revision number, compilation date and optionally copyrigth or author info. The version string is decoded by many applications including Ambient, the system command ''version'', the Installer program and more. The text starts with '''$VER:''', so it can be easily found in the program executable. As version tools search for the version string from the start of the executable file, it is best if version string is placed as close to the beginning of the file as possible. If the version string is declared as a simple string constant, it is unfortunately placed in one of the ELF data sections. These sections are placed after the code section by the linker. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into the ELF section named ''.text'', which is the code section. As the startup code object is linked as the first object, the version string will appear at the beginning of the executable, just after the code of the ''Start()'' function. Why after? It is simple, if we place it before the real code, the operating system will jump "into" the string, trying to execute it, and then of course it will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows the described ideas at work. It only uses the MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T13:39:24Z

Krashan: even more fixes

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a signal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([[Installation of Software Development Kit and its basic usage#Standard C and C++ Libraries|more on this]]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When the program is linked with ''libnix'', the possibility of using own startup depends on the standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should use '''−nostdlib''' option, which also implies '''−nostdlib'''.

=Let's Write It=

Before we start to write the code, note that except things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (the one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()'' function. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. The GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note it is time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts with including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase;
struct Library *DOSBase;

As our code will use these two libaries, we need to define their bases.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, our code won't run.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from the ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns the calling task's own descriptor if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'' function, if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' may fail for other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what does ''Forbid()'' do here? This function halts system multitasking, specifically it prevents the system process scheduler to switch our process away. Usually it may be done for a very short period of time only and followed by a matching ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when the process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies the Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but the version string is usually placed in it, so I've decided to write a few words about it. The version string is a short text in some defined format. This string contains the program name, version and revision number, compilation date and optionally copyrigth or author info. The version string is decoded by many applications including Ambient, the system command ''version'', the Installer program and more. The text starts with '''$VER:''', so it can be easily found in the program executable. As version tools search for the version string from the start of the executable file, it is best if version string is placed as close to the beginning of the file as possible. If the version string is declared as a simple string constant, it is unfortunately placed in one of the ELF data sections. These sections are placed after the code section by the linker. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into the ELF section named ''.text'', which is the code section. As the startup code object is linked as the first object, the version string will appear at the beginning of the executable, just after the code of the ''Start()'' function. Why after? It is simple, if we place it before the real code, the operating system will jump "into" the string, trying to execute it, and then of course it will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows the described ideas at work. It only uses the MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T13:37:52Z

Krashan: More fixes.

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a signal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([[Installation of Software Development Kit and its basic usage#Standard C and C++ Libraries|more on this]]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When the program is linked with ''libnix'', the possibility of using own startup depends on the standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should use '''−nostdlib''' option, which also implies '''−nostdlib'''.

=Let's Write It=

Before we start to write the code, note that except things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (the one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()'' function. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. The GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note it is time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts with including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase;
struct Library *DOSBase;

As our code will use these two libaries, we need to define their bases.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, our code won't run.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from the ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns own descriptor of the caller if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'' function, if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' may fail for other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what does ''Forbid()'' do here? This function halts system multitasking, specifically it prevents the system process scheduler to switch our process away. Usually it may be done for a very short period of time only and followed by a matching ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when the process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies the Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but the version string is usually placed in it, so I've decided to write a few words about it. The version string is a short text in some defined format. This string contains the program name, version and revision number, compilation date and optionally copyrigth or author info. The version string is decoded by many applications including Ambient, the system command ''version'', the Installer program and more. The text starts with '''$VER:''', so it can be easily found in the program executable. As version tools search for the version string from the start of the executable file, it is best if version string is placed as close to the beginning of the file as possible. If the version string is declared as a simple string constant, it is unfortunately placed in one of the ELF data sections. These sections are placed after the code section by the linker. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into the ELF section named ''.text'', which is the code section. As the startup code object is linked as the first object, the version string will appear at the beginning of the executable, just after the code of the ''Start()'' function. Why after? It is simple, if we place it before the real code, the operating system will jump "into" the string, trying to execute it, and then of course it will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows the described ideas at work. It only uses the MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T13:24:37Z

Krashan: Fixes.

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a signal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([[Installation of Software Development Kit and its basic usage#Standard C and C++ Libraries|more on this]]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When the program is linked with ''libnix'', the possibility of using own startup depends on the standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should use '''−nostdlib''' option, which also implies '''−nostdlib'''.

=Let's Write It=

Before we start to write the code, note that except things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (the one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()'' function. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. The GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note it is time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts with including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase = 0;
struct Library *DOSBase = 0;

As our code will use these two libaries, we need to define their bases. In fact global variables are zeroed automatically, but I've written it explicitly just in case. It also increases code readability a bit.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, our code won't run.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from the ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns own descriptor of the caller if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'' function, if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' may fail for other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what does ''Forbid()'' do here? This function halts system multitasking, specifically it prevents the system process scheduler to switch our process away. Usually it may be done for a very short period of time only and followed by a matching ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when the process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies the Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but the version string is usually placed in it, so I've decided to write a few words about it. The version string is a short text in some defined format. This string contains the program name, version and revision number, compilation date and optionally copyrigth string, or author info. Version string is decoded by many applications including Ambient, system command ''version'', Installer program and more. The text starts from '''$VER:''', so it can be easily found in the program executable. As version tools search for version string from the start of executable file, it is best if version string is placed as near to the start as possible. If version string is declared as a simple string constant, it is unfortunately placed in one of ELF data sections. These sections are placed by compiler after the code section. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into ELF section named ''.text'', which is the code section. As the startup code object is linked as the first, version string will appear at the beginning of the executable, just after code of ''Start()'' function. Why after? It is simple, if we place it before the real code, operating system will jump "into" the string, trying to execute it, and then of course will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows described ideas at work. It uses only MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T12:31:06Z

Krashan: Fixed internal link.

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a singal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([[Installation of Software Development Kit and its basic usage#Standard C and C++ Libraries|more on this]]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When program is linked with ''libnix'', possibility of using own startup depends on standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should add '''−nostdlib''' to it.

=Let's Write It=

Before we start to write the code, note that except of things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()''. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write a code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts from including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase = 0;
struct Library *DOSBase = 0;

As our code will use these two libaries, we need to define their bases. In fact global variables are zeroed automatically, but I've written it explicitly just in case. It also increases code readability a bit.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, our code won't run.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns own descriptor of the caller if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'', if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening the ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. The ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' fail may have other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what ''Forbid()'' does here? This function halts system multitasking, precisely it prevents the system process scheduler to switch our process away. Usually it may be done for very short period of time only and followed by matched ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but version string is usually placed in it, so I've decided to write a few words about it. Version string is a short text in some defined format. This text contains the program name, version and revision number, compilation date and optionally copyrigth string, or author info. Version string is decoded by many applications including Ambient, system command ''version'', Installer program and more. The text starts from '''$VER:''', so it can be easily found in the program executable. As version tools search for version string from the start of executable file, it is best if version string is placed as near to the start as possible. If version string is declared as a simple string constant, it is unfortunately placed in one of ELF data sections. These sections are placed by compiler after the code section. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into ELF section named ''.text'', which is the code section. As the startup code object is linked as the first, version string will appear at the beginning of the executable, just after code of ''Start()'' function. Why after? It is simple, if we place it before the real code, operating system will jump "into" the string, trying to execute it, and then of course will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows described ideas at work. It uses only MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T11:31:22Z

Krashan: Added author name

''Grzegorz Kraszewski''

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a singal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([morphos-sdk#Standard C and C++ Libraries|more on this]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When program is linked with ''libnix'', possibility of using own startup depends on standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should add '''−nostdlib''' to it.

=Let's Write It=

Before we start to write the code, note that except of things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()''. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write a code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts from including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase = 0;
struct Library *DOSBase = 0;

As our code will use these two libaries, we need to define their bases. In fact global variables are zeroed automatically, but I've written it explicitly just in case. It also increases code readability a bit.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, our code won't run.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns own descriptor of the caller if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'', if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening the ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. The ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' fail may have other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what ''Forbid()'' does here? This function halts system multitasking, precisely it prevents the system process scheduler to switch our process away. Usually it may be done for very short period of time only and followed by matched ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but version string is usually placed in it, so I've decided to write a few words about it. Version string is a short text in some defined format. This text contains the program name, version and revision number, compilation date and optionally copyrigth string, or author info. Version string is decoded by many applications including Ambient, system command ''version'', Installer program and more. The text starts from '''$VER:''', so it can be easily found in the program executable. As version tools search for version string from the start of executable file, it is best if version string is placed as near to the start as possible. If version string is declared as a simple string constant, it is unfortunately placed in one of ELF data sections. These sections are placed by compiler after the code section. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into ELF section named ''.text'', which is the code section. As the startup code object is linked as the first, version string will appear at the beginning of the executable, just after code of ''Start()'' function. Why after? It is simple, if we place it before the real code, operating system will jump "into" the string, trying to execute it, and then of course will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows described ideas at work. It uses only MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Writing Custom Startup Code

2012-12-29T11:30:37Z

Krashan: Added new article.

One can find in every C programming handboook, that program execution starts from ''main()'' function. In fact we have such an impression, when we write a program. There is no evidence to disprove it. In fact however, this is not true. There are at least a few, and sometimes even a few teens of kilobytes of code between the start of program execution and the first line of ''main()''. Most of this code is not really needed in most cases.

What is being done by this code? Let's say for the start, it is perfectly possible to have a program without any startup code at all. The system can jump into ''main()'' right away. Unfortunately such a program would run only from commandline window. It would crash, when started from Ambient. It is because Ambient sends a special message to a message port of a freshly created process. This message serves two purposes. Firstly, it contains Ambient launch parameters, namely program icon descriptor and optionally descriptors of other icons, which have been shift-clicked, or dropped onto a panel. Secondly, a reply for the message is a singal for Ambient that the program finished its execution. Sending a reply is obligatory. This is the minimal set of things to be done by startup code. In practice it also should open required shared libraries. When one wants to use the C standard library, either with ''libnix'' or ''ixemul.library'', the startup code also creates a "standard environment" for the C standard library and POSIX functions ([morphos-sdk#Standard C and C++ Libraries|more on this]). Because of this, startup code linked when using one of these libraries is quite complex, so also long.

=Reasons for Writing Own Startup=

The main advantage of an own startup is its shortness. Reducing program startup time is negligible. Very short startup is good for very short programs (for example shell commands), a few kB in size. In this case the standard startup may be easily longer than the program code itself. One can also use own startup just for satisfaction of making the program shorter by those few kilobytes. Custom startup code cannot be used, when the program uses ''ixemul.library''. When program is linked with ''libnix'', possibility of using own startup depends on standard C library functions used. Most of them do not need any preparations and will work with any startup. Some more complex functions however require constructors to be executed in startup. If we use such functions, we will get linker errors of unresolved symbols. In such a case there is a simple choice – one either must replace these functions with something else, or just use the standard startup code. Own startup is then useful mostly when standard C library is not used at all (in favour of the native MorphOS API), or only simple functions from it are used.

If we are still determined to use own startup, it is the time to tell the compiler about it. Skipping standard startup is done with '''−nostartfiles''' argument. Then when we try to use our startup with ''libnix'', we use '''−nostartfiles''' together with '''−noixemul'''. Programmers wanting to go the pure MorphOS API way (without the C library), should add '''−nostdlib''' to it.

=Let's Write It=

Before we start to write the code, note that except of things executed before calling the ''main()'' function, some code must be also called '''after''' it returns. Then we also have "cleanup code". As this code is usually placed in the same function (one that calls ''main()''), both the parts are commonly called just startup code.

As mentioned before, program execution does not really start from the ''main()''. Where does it start then? When an ELF executable is loaded from disk, a section named ".text" is found and operating system jumps to the start of its contents. When a program is written in C, it means start of the first function in code, as in C there is no way to write a code outside of a function. It must be noted, that C compiler may reorder functions in a single object file. GCC 2.95.3 compiler never does it, but aggressive optimizer of GCC 4 can change order of functions. Fortunately it is done only inside a single source file. To make sure that our startup function will be the first, it must be placed in a separate file. Then resulting object file must be linked as the first one, as linking order is always preserved. After this important note time for the code:

#include <proto/exec.h>
#include <proto/dos.h>
#include <dos/dos.h>
#include <workbench/startup.h>

The thing starts from including needed header files. We will need two basic system libraries: ''exec.library'' and ''dos.library''. It explains why standard startup code, be it ''libnix'' or ''ixemul.library'', opens these two libraries – it simply needs them for itself.

struct Library *SysBase = 0;
struct Library *DOSBase = 0;

As our code will use these two libaries, we need to define their bases. In fact global variables are zeroed automatically, but I've written it explicitly just in case. It also increases code readability a bit.

extern ULONG Main(struct WBStartup *wbmessage);

This is a declaration of the main function of our program. As the object file containing startup code should contain only one function (the entry one), the rest of code has to be moved to other object files, for reasons explained above. That is why the main function has to be declared here, as we call it from the startup code. Alternatively its declaration may be placed in some header file and included here. The name ''Main()'' is arbitrary, it can be anything. I've just called it typically, capitalizing the first letter to avoid possible name confilct with the standard library. The argument of ''Main()'' is startup message (mentioned above) being sent by Ambient. If we do not plan to use it inside ''Main()'', we can just declare it this way:

extern ULONG Main(void);

The next important thing is to define a mysterious global symbol ''__abox__''.

ULONG __abox__ = 1;

While not needed in the code, this symbol is used by the system executable loader to differentiate between MorphOS ELF executables and other possible PowerPC ELF binaries. If there is no ''__abox__'' defined, our code won't run.

ULONG Start(void)
{
struct Process *myproc = 0;
struct Message *wbmessage = 0;
BOOL have_shell = FALSE;
ULONG return_code = RETURN_OK;

''Start()'' is the code entry point. Again, name of this function is not important, it may be anything. It just has to be the first function in the linked executable. Some local variables are declared here, which will be needed later. ''myproc'' will contain a pointer to our process, ''wbmessage'' will hold the Ambient startup message pointer. Variable ''have_shell'' will be used to detect if the program has been started from shell console or from Ambient. Finally ''return_code'' is just the return code of the program, it will be returned to the system. The return value is usually 0 when the program executed succesfully and ''RETURN_OK'' constant is just 0.

SysBase = *(struct Library**)4L;

Time for initialization of the ''SysBase'', the base of ''exec.library''. The library is always open. For historical and backward compatibility reasons the base pointer is always placed by the system at address $00000004, so we just take it from there. Having ''exec.library'' available, our code can check whether it has been started from shell or from Ambient:

myproc = (struct Process*)FindTask(0);
if (myproc->pr_CLI) have_shell = TRUE;

This information is taken from ''Process'' structure being just system process descriptor. The ''exec.library'' call ''FindTask()'' returns own descriptor of the caller if 0 is passed as its argument. In case we are started from Ambient, receiving its message is compulsory:

if (!have_shell)
{
WaitPort(&myproc->pr_MsgPort);
wbmessage = GetMsg(&myproc->pr_MsgPort);
}

The startup message is being sent to process system port, so we receive it there. The message may be then passed to our ''Main()'', if we plan to make some use of it, like handling additional icon arguments.

if (DOSBase = OpenLibrary((STRPTR)"dos.library", 0))
{

The next step is opening the ''dos.library'', this library is opened in a pretty standard way. In fact this minimal startup code does not need it. There are two reasons to open it anyway. First, it is hard to imagine a program, which does not need ''dos.library'' – even "Hello world!" needs it. Secondly, all standard startup codes open it, so usually main code takes it for granted. Then my startup behaves conventionally and opens ''dos.library'' as well.

return_code = Main((struct WBStartup*)wbmessage);

Yes, after these few lines we are ready to call the main code. As stated above, passing the startup message from Ambient is optional. On the other hand, receiving the result and passing it back to the system later is obligatory.

CloseLibrary(DOSBase);
}
else return_code = RETURN_FAIL;

From this point the startup code becomes cleanup one. Note also that proper error handling must be done. The ''dos.library'' is being closed, but if its opening failed before, the result of execution is changed to ''RETURN_FAIL''. This is the hardest fail and means total inability to execute. In practice MorphOS can't boot if ''dos.library'' is not present in the system. But ''OpenLibrary()'' fail may have other reasons, for example simple lack of free memory. Then the startup code has to handle it in some reasonable way.

if (wbmessage)
{
Forbid();
ReplyMsg(wbmessage);
}

This snippet of code handles the Ambient startup message. Even if we make no use of it, it '''must''' be replied at exit. But what ''Forbid()'' does here? This function halts system multitasking, precisely it prevents the system process scheduler to switch our process away. Usually it may be done for very short period of time only and followed by matched ''Permit()''. At the first glance this code makes no sense then, a process stops process switching and... exits. We have to know one important thing however: process switching is automatically reenabled when process which called ''Forbid()'' ends. Then here is what happens:
* Our task calls ''Forbid()'', so no other process can interrupt it.
* It replies Ambient startup message. As multitasking is stopped, Ambient is unable to receive yet. The message just waits at its message port.
* Our task exits. Then the system restores multitasking.
* Ambient gets CPU time and receives the message. Note that at this point it is absolutely certain, that our task does not exist anymore. Possibility of a race condition is eliminated. Without ''Forbid()'' it could be possible that our process is removed from the system while it still executes.
Of course multitasking halt period is extremely short, because our cleanup code ends immediately after replying to Ambient:

return return_code;
}

=$VER: – program identification string=

This topic is not strictly related to startup code, but version string is usually placed in it, so I've decided to write a few words about it. Version string is a short text in some defined format. This text contains the program name, version and revision number, compilation date and optionally copyrigth string, or author info. Version string is decoded by many applications including Ambient, system command ''version'', Installer program and more. The text starts from '''$VER:''', so it can be easily found in the program executable. As version tools search for version string from the start of executable file, it is best if version string is placed as near to the start as possible. If version string is declared as a simple string constant, it is unfortunately placed in one of ELF data sections. These sections are placed by compiler after the code section. However we can force the version string to be placed in the code section:

__attribute__ ((section(".text"))) UBYTE VString[] =
"$VER: program 1.0 (21.6.2011) © 2011 morphos.pl\r\n";

Using a GCC specific extension ''__attribute__'' we can push the string into ELF section named ''.text'', which is the code section. As the startup code object is linked as the first, version string will appear at the beginning of the executable, just after code of ''Start()'' function. Why after? It is simple, if we place it before the real code, operating system will jump "into" the string, trying to execute it, and then of course will crash.

=A Complete Example=

A complete "Hello world!" [http://krashan.ppa.pl/mph/files/helloworld.lha example] with custom startup code shows described ideas at work. It uses only MorphOS API, so is compiled with '''−nostdlib''' option. Executable size is 1 592 bytes. For comparision, ''libnix'' startup and ''printf()'' gives 30 964 bytes, when one replaces ''printf()'' with MorphOS ''Printf()'' from ''dos.library'' it is still 13 500 bytes.

As the project consists of two *.c files, a simple makefile is added to it. Example may be compiled just by entering ''make'' in a console.

Advanced Topics

2012-12-29T11:26:32Z

Krashan: First advanced topic added.

*[[Writing Custom Startup Code]]

Main Page

2012-12-29T11:25:20Z

Krashan: /* Development */ added "Advanced Topics"

__NOTOC__

<div id="siteLogo" style="float: right;"> </div>

<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#274572;">Welcome to the MorphOS Library,</div>
<div style="top:+0.2em; font-size:95%;">the wiki based library of MorphOS related documentation.</div>

Do you have suggestions or would like to contribute? Please contact: <div id="message2library"></div>

'''Important notes to editors:''' [[Basic Guidelines]] - [[List of Wanted Articles]]

----
<small>This page in other languages: [[Strona główna|Polish]]</small>

==About MorphOS==
MorphOS - The Lightning OS
* [[What is MorphOS?]]
* [[Hardware Platforms]]
* [[Installation]]
* [[Characteristic features]]
* [[MorphOS integration]]
* [[MorphOS Development]]
* [[Developer tools]]
* [[3D graphics]]
* [[Games]]
* [[MorphOS key applications]]
* [[Platform expansion]]
* [[Who needs MorphOS?]]
* [[Conclusions]]
* [[Useful links]]
* [[F.A.Q.]]
* [[Historical notes]]
* [[Contributors]]
A five minute read for users familiar with the Commodore Amiga
*[[MorphOS in 5 minutes]]

==Articles==
The core of the MorphOS Library can be found here. Along with the provided manuals, there are several documents designed to help users get the most out of their MorphOS powered computer.

* [[Fundamentals of MorphOS]]
* [[Dictionary of Terms]]
* [[Shell Commands|Shell: Commands]]
* [[Pattern matching|Shell: Pattern Matching]]
* [[Volume Names]]

==Tutorials==
Welcome to the Tutorials section of the MorphOS Library. In this aisle of the library you can find examples and step by step instructions to help get the most out of your MorphOS experience.

*[[Modifying the User-Startup file]]
*[[Dual-boot MorphOS and MacOS X on a Mac Mini G4]]
*[[How to write Mails with SimpleMail]]
*[[MorphOS External USB Drive Backup Guide]]
*[[Scanning with SCANdal]]
*[[Recording an LP with Audio Evolution 4]]
*[[Passwordless SSH login with RemoteShell]]

==Development==
In the development section of the MorphOS Library, you can find a collection of helpful articles and tutorials focused on MorphOS software development.

*[[First steps in MorphOS programming]]
*[[Magic User Interface Programming]]
*[[In-depth: The New MorphOS Memory System]]
*[[Reggae: MorphOS multimedia framework]]
*[[An Introduction to MorphOS PPC Assembly]]
*[[Advanced Topics]]

==Benchmarks, Reports & Reviews==
*[[jPV's MorphOS 2 Review]]

==Links==
The MorphOS Link Database is a collection of websites that are of interest to all current and potential future users of MorphOS. For easier navigation, we have separated the list of websites into multiple categories.

*[[Links#Community_Portals_.26_Forums|Community Portals]]
*[[Links#File_Repositories|File Repositories]]
*[[Links#Software|Software]]
*[[Links#Developers|Developers]]
*[[Links#Misc|Misc]]

==Work in Progress==
*[[ReTooled]]

The First Traditional "Hello world!"

2012-10-19T06:15:01Z

Krashan: /* "Hello World!" With the MorphOS Native API */ style

''Grzegorz Kraszewski''
----
<small>This page in other languages: [[Pierwsze tradycyjne "Hello world!"|Polish]]</small>

=="Hello World!" With the Standard C Library==

With the standard C library, one can use the "Hello World!" example exactly as found in a C handbook. It is given below, just for completeness:

<tt>#include <stdio.h><br><br>
int main(void)<br>
{<br>
  printf("Hello World!\n");<br>
  return 0;<br>
}<br></tt>

This source may be copied to a text editor and saved as ''helloworld.c''. To compile it, one opens a shell window (from the Ambient menu, or using the ''rcommand + n'' key combo) and changes current directory to the one, where the C source is located. The compiler is run as follows:

<tt>gcc -o helloworld helloworld.c</tt>

The compiler produces a ''helloworld'' executable, which is 10 340 bytes on my system. Note that MorphOS pays little attention to filename extensions, so ending the executable name with ''.exe'' is not needed, however, it can be done. Traditionally MorphOS executables are named without any extensions. The '''−o''' compiler option specifies a desired executable name. If this option is not given, the executable will be named ''a.out'' (for some historical reasons).

As stated in the [[Installation_of_Software_Development_Kit_and_its_basic_usage#Standard_C_and_C++_Libraries|SDK section]], the standard C library will be provided by ''ixemul.library''. It can be easily confirmed by tracing the disk activity of ''helloworld'' using the ''Snoopium'' tool.

[[File:snoopium_ixemul.png]]

It can also be seen that many other libraries are also opened including ones related to TCP/IP networking. It looks like overkill for such a small program. This happens, because ''ixemul.library'' creates a complete unixlike environment for the application, which is not needed in this simple case. That is why the ''libnix'' alternative is recommended for use of the standard library. To use it, a '''−noixemul''' option has to be added, so the compiler is called as follows:

<tt>gcc -noixemul -o helloworld helloworld.c</tt>

The generated executable is much larger (30 964 bytes here), which just confirms the fact, that ''libnix'', which is now in use, is a statically linked library. Size of functions used adds to the size of the executable. Every C handbook states, that ''printf()'' is the most expensive function of standard I/O, which has just been proven experimentally... On the other hand program activity, as traced with ''Snoopium'', is reduced to three entries. No external resources are opened.

=="Hello World!" With the MorphOS Native API==

The MorphOS API (''Application Programmer Interface'') provides complete file and console input/output. In fact, functions in C and C++ standard libraries are, more or less complex wrappers around MorphOS native calls. Using the native API has the following advantages:

* Programs are much shorter.
* Programs are faster, thanks to stripping some layers of abstraction.
* Programs are less resource hungry.
* Native API gives full access to MorphOS specific features.

These advantages come at a price:

* Programs using the native API are not portable (except for porting to AmigaOS and AROS to some degree).
* Native ''printf()''-like functions do not support floating point numbers.

The "Hello World!" example using the native API is as follows:

<tt>#include <proto/dos.h><br><br>
int main(void)<br>
{<br>
  Printf("Hello World!\n");<br>
  return 0;<br>
}</tt>

The included header includes all things needed to use the ''dos.library'', where the ''Printf()'' function is located. The function itself works the same as the standard library ''printf()'', with some minor differences. The code is compiled with this command:

<tt>gcc -noixemul -o helloworld helloworld.c</tt>

The command is the same as that used for the program using ''libnix'' and the standard library ''printf()'', however, the standard C function is not used, so it is not linked. Now the executable size reduces to 13 500 bytes.

Why is ''libnix'' still needed in spite of the standard library calls not being used? Can't one just compile with '''−nostdlib'''? Other than the standard C library, ''libnix'' also provides application startup code. A program without this startup code can still work when launched from the shell, but will crash when started from Ambient. The startup code also provides an automatic MorphOS library opening and closing feature. So, excluding ''libnix'' completely is possible, but requires [[writing your own startup code]] and [[MorphOS_API_and_Its_Organization#Manual_Library_Opening_and_Closing|handling library opening and closing manually]].

<small>Note: excluding ''libnix'' is usually done for MorphOS components other than applications, like shared libraries or Reggae and MUI public classes. It can also be done for ordinary programs just to make them shorter, especially if a program is small. For bigger projects bytes saved by writing custom startup code are not usually worth the effort.</small>

Installation of Software Development Kit and its basic usage

2012-10-19T06:12:25Z

Krashan: /* Choosing a Compiler */ style

''Grzegorz Kraszewski''
----
<small>This page in other languages: [[Instalacja SDK (Software Development Kit) i podstawy jego używania|polski]]</small>

==Installing the SDK==

The official MorphOS SDK provides a complete environment for creating programs
for MorphOS. It contains the following components:

* MorphOS includes (for the MorphOS native API).
* Standard C and C++ library includes.
* MorphOS API documentation and example code.
* Two GCC compilers, 2.95.3 and 4.4.5.
* GCC toolchains (one for each compiler), sets of developer utility programs.
* ''Scribble'', an advanced programmer's editor with syntax highlighting and powerful autocomplete and code analyser/hinter feature.
* Perl scripting language (used by some SDK tools).

The first step of installation is to download the SDK archive from the [http://www.morphos.net morphos.net] site, or by clicking this [http://www.morphos-team.net/files/sdk-20110916.lha direct link]. The SDK is delivered as a LhA archive, which must be depacked before proceeding. The easiest way is to open a context menu for the archive (with the right mouse button in an Ambient window) and choose ''Extract''. After depacking a directory named ''morphossdk'' is created with an ''Installer'' application and a big file named ''sdk.pack'' inside. Installation is started by running ''Installer''. The only user choice that is needed here is to choose an installation directory. Then there is some time spent watching the progress bar...

After the installation a system reboot may be needed to update system assigns and paths.

==Choosing a Compiler==

As mentioned above, the SDK delivers two GCC compilers: an old but trusty 2.95.3 one, and the modern 4.4.5. There is a tool named ''GCCSelect'' in the SDK, which allows for fast switching between compilers. Just type in a shell window

<tt>GCCSelect 2.95.3</tt>

or

<tt>GCCSelect 4.4.5</tt>

to change the current compiler. ''GCCSelect'' works by making symbolic links to the proper version of GCC and its tools, so the compiler is always called as ''gcc'' or ''g++'', regardless of the version chosen currently.

Which one to choose? It depends on the code compiled and other constrains. Here is some guidance:

* 2.95.3 compiles faster and consumes less memory.
* For old code 2.95.3 would be better, as GCC 4 will produce tons of warnings or even errors on code being flawlessly compiled by the old GCC.
* For new projects, especially written in C++, GCC 4 is recommended, as the old one simply does not keep up with modern standards.
* GCC 4 usually produces faster code (but sometimes also bigger, depending on optimizer options).
* GCC 4 is a relatively new and complex compiler, may contain more bugs than 2.95.3.

My general advice is to use GCC 4 and only switch to GCC 2 if needed.

One can check which compiler is currently active using the '''−v''' compiler option, which displays the compiler version and build options:

<tt>gcc -v</tt>

The last line of output shows the GCC version.

==Standard C and C++ Libraries==

These standard libraries are parts of the C and C++ language specifications respectively. They mainly deliver file and console input/output functions, mathematic functions and string operations. The C++ library also provides a set of basic container classes.

* [http://en.wikipedia.org/wiki/C_standard_library C standard library on Wikipedia]
* [http://en.wikipedia.org/wiki/C%2B%2B_Standard_Library C++ standard library on Wikipedia]

There are two ways to access these libraries on MorphOS. The first (and default) one is by using a MorphOS [[MorphOS_API_and_Its_Organization|shared library]]; ''ixemul.library''. As the name suggests, this library tries to provide some Unix environment emulation on MorphOS, which, other than the standard libraries, includes large part of [http://en.wikipedia.org/wiki/Posix POSIX] standard and some other commonly used functions. ''ixemul.library'' is usually used for porting big projects from the Unix/Linux world, for example it is used by GCC itself and many other tools in the SDK.

The second way is to use ''libnix'' (as in; '''''lib''' '''n'''o '''ix'''emul''). In contrast to ''ixemul.library'', ''libnix'' is statically linked with the application. This is the preferred way for providing standard libraries for MorphOS native applications. It is achieved by passing the '''−noixemul''' flag to the compiler and the linker. ''libnix'' delivers full C and C++ standard libraries, but its POSIX implementation is less complete.

<small>Another alternative is to not use standard libraries at all. It may sound crazy at first, but the MorphOS native API provides complete file and console I/O as well as some string manipulation functions and many mathematic functions. Using the native API makes applications faster and smaller in size. On the other hand code using the MorphOS API directly is not portable to non-Amiga(like) systems. A '''−nostdlib''' compiler option instructs the compiler to not link the code with the standard library. Note that this requires also writing your own [[Custom Startup Code|custom startup code]].</small>

Installation of Software Development Kit and its basic usage

2012-10-19T06:11:30Z

Krashan: /* Installing the SDK */ Scribble

''Grzegorz Kraszewski''
----
<small>This page in other languages: [[Instalacja SDK (Software Development Kit) i podstawy jego używania|polski]]</small>

==Installing the SDK==

The official MorphOS SDK provides a complete environment for creating programs
for MorphOS. It contains the following components:

* MorphOS includes (for the MorphOS native API).
* Standard C and C++ library includes.
* MorphOS API documentation and example code.
* Two GCC compilers, 2.95.3 and 4.4.5.
* GCC toolchains (one for each compiler), sets of developer utility programs.
* ''Scribble'', an advanced programmer's editor with syntax highlighting and powerful autocomplete and code analyser/hinter feature.
* Perl scripting language (used by some SDK tools).

The first step of installation is to download the SDK archive from the [http://www.morphos.net morphos.net] site, or by clicking this [http://www.morphos-team.net/files/sdk-20110916.lha direct link]. The SDK is delivered as a LhA archive, which must be depacked before proceeding. The easiest way is to open a context menu for the archive (with the right mouse button in an Ambient window) and choose ''Extract''. After depacking a directory named ''morphossdk'' is created with an ''Installer'' application and a big file named ''sdk.pack'' inside. Installation is started by running ''Installer''. The only user choice that is needed here is to choose an installation directory. Then there is some time spent watching the progress bar...

After the installation a system reboot may be needed to update system assigns and paths.

==Choosing a Compiler==

As mentioned above, the SDK delivers two GCC compilers: an old but trusty 2.95.3 one, and the modern 4.4.5. There is a tool named ''GCCSelect'' in the SDK, which allows fast switching between compilers. Just type in a shell window

<tt>GCCSelect 2.95.3</tt>

or

<tt>GCCSelect 4.4.5</tt>

to change the current compiler. ''GCCSelect'' works by making symbolic links to the proper version of GCC and its tools, so the compiler is always called as ''gcc'' or ''g++'', regardless of the version chosen currently.

Which one to choose? It depends on the code compiled and other constrains. Here is some guidance:

* 2.95.3 compiles faster and consumes less memory.
* For old code 2.95.3 would be better, as GCC 4 will produce tons of warnings or even errors on code being flawlessly compiled by the old GCC.
* For new projects, especially written in C++, GCC 4 is recommended, as the old one simply does not keep up with modern standards.
* GCC 4 usually produces faster code (but sometimes also bigger, depending on optimizer options).
* GCC 4 is a relatively new and complex compiler, may contain more bugs than 2.95.3.

My general advice is to use GCC 4 and only switch to GCC 2 if needed.

One can check which compiler is currently active using the '''−v''' compiler option, which displays the compiler version and build options:

<tt>gcc -v</tt>

The last line of output shows the GCC version.

==Standard C and C++ Libraries==

These standard libraries are parts of the C and C++ language specifications respectively. They mainly deliver file and console input/output functions, mathematic functions and string operations. The C++ library also provides a set of basic container classes.

* [http://en.wikipedia.org/wiki/C_standard_library C standard library on Wikipedia]
* [http://en.wikipedia.org/wiki/C%2B%2B_Standard_Library C++ standard library on Wikipedia]

There are two ways to access these libraries on MorphOS. The first (and default) one is by using a MorphOS [[MorphOS_API_and_Its_Organization|shared library]]; ''ixemul.library''. As the name suggests, this library tries to provide some Unix environment emulation on MorphOS, which, other than the standard libraries, includes large part of [http://en.wikipedia.org/wiki/Posix POSIX] standard and some other commonly used functions. ''ixemul.library'' is usually used for porting big projects from the Unix/Linux world, for example it is used by GCC itself and many other tools in the SDK.

The second way is to use ''libnix'' (as in; '''''lib''' '''n'''o '''ix'''emul''). In contrast to ''ixemul.library'', ''libnix'' is statically linked with the application. This is the preferred way for providing standard libraries for MorphOS native applications. It is achieved by passing the '''−noixemul''' flag to the compiler and the linker. ''libnix'' delivers full C and C++ standard libraries, but its POSIX implementation is less complete.

<small>Another alternative is to not use standard libraries at all. It may sound crazy at first, but the MorphOS native API provides complete file and console I/O as well as some string manipulation functions and many mathematic functions. Using the native API makes applications faster and smaller in size. On the other hand code using the MorphOS API directly is not portable to non-Amiga(like) systems. A '''−nostdlib''' compiler option instructs the compiler to not link the code with the standard library. Note that this requires also writing your own [[Custom Startup Code|custom startup code]].</small>

Reggae tutorial: Saving audio in user selected format

2012-10-09T11:37:02Z

Krashan: /* Saver Control Without GUI */ Image added.

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

[[File:Saver_API.png|center]]

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.

Compared to GUI, the textual interface to Reggae savers has two shortcomings:
* User (or application, if the argument string is not given by user) has to know which multiplexers are installed in the system and has to know encoder parameters.
* GUI is designed in a way, that does not allow user to enter senseless or conflicting combinations of parameters (for example ''rawaudio.muxer'' GUI automatically disables "Byte Order" gadget, when 8-bit samples are selected). For textual definition parameter validation is done when Reggae chain is built, and ''MediaBuildFromArgsTags()'' simply fail when arguments make no sense.

==Yet Another Example==
The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor Zgrzytor]. Unlike Zormanita and U1Synth, it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:

Zgrzytor 3 11 22050 somenoise.wav '''WAVE BITS=32'''

This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) of the shift register and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

File:Saver API.png

2012-10-09T11:35:37Z

Krashan: Reggae saver API functions

Reggae saver API functions

Reggae tutorial: Saving audio in user selected format

2012-10-08T19:32:04Z

Krashan: /* Yet Another Example */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.

Compared to GUI, the textual interface to Reggae savers has two shortcomings:
* User (or application, if the argument string is not given by user) has to know which multiplexers are installed in the system and has to know encoder parameters.
* GUI is designed in a way, that does not allow user to enter senseless or conflicting combinations of parameters (for example ''rawaudio.muxer'' GUI automatically disables "Byte Order" gadget, when 8-bit samples are selected). For textual definition parameter validation is done when Reggae chain is built, and ''MediaBuildFromArgsTags()'' simply fail when arguments make no sense.

==Yet Another Example==
The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor Zgrzytor]. Unlike Zormanita and U1Synth, it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:

Zgrzytor 3 11 22050 somenoise.wav '''WAVE BITS=32'''

This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) of the shift register and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

Reggae tutorial: Saving audio in user selected format

2012-10-08T19:30:45Z

Krashan: /* Yet Another Example */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.

Compared to GUI, the textual interface to Reggae savers has two shortcomings:
* User (or application, if the argument string is not given by user) has to know which multiplexers are installed in the system and has to know encoder parameters.
* GUI is designed in a way, that does not allow user to enter senseless or conflicting combinations of parameters (for example ''rawaudio.muxer'' GUI automatically disables "Byte Order" gadget, when 8-bit samples are selected). For textual definition parameter validation is done when Reggae chain is built, and ''MediaBuildFromArgsTags()'' simply fail when arguments make no sense.

==Yet Another Example==
The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor Zgrzytor]. Unlike Zormanita and U1Synth, it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:

Zgrzytor 3 11 22050 '''WAVE BITS=32'''

This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) of the shift register and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

Reggae tutorial: Saving audio in user selected format

2012-10-08T19:29:10Z

Krashan: /* Yet Another Example */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.

Compared to GUI, the textual interface to Reggae savers has two shortcomings:
* User (or application, if the argument string is not given by user) has to know which multiplexers are installed in the system and has to know encoder parameters.
* GUI is designed in a way, that does not allow user to enter senseless or conflicting combinations of parameters (for example ''rawaudio.muxer'' GUI automatically disables "Byte Order" gadget, when 8-bit samples are selected). For textual definition parameter validation is done when Reggae chain is built, and ''MediaBuildFromArgsTags()'' simply fail when arguments make no sense.

==Yet Another Example==
The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor|Zgrzytor]. Unlike Zormanita ans U1Synth it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:

Zgrzytor 3 11 22050 '''WAVE BITS=32'''

This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). The last, emboldened part of the call is just Reggae saver argument string. More about Zgrzytor can be found on its homepage. Of course full source code of Zgrzytor is added to the archive.

Reggae tutorial: Saving audio in user selected format

2012-10-08T19:28:11Z

Krashan:

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.

Compared to GUI, the textual interface to Reggae savers has two shortcomings:
* User (or application, if the argument string is not given by user) has to know which multiplexers are installed in the system and has to know encoder parameters.
* GUI is designed in a way, that does not allow user to enter senseless or conflicting combinations of parameters (for example ''rawaudio.muxer'' GUI automatically disables "Byte Order" gadget, when 8-bit samples are selected). For textual definition parameter validation is done when Reggae chain is built, and ''MediaBuildFromArgsTags()'' simply fail when arguments make no sense.

==Yet Another Example==
The third example application using Reggae saver API is [http://krashan.ppa.pl/articles/zgrzytor|Zgrzytor]. Unlike Zormanita ans U1Synth it is a shell command using textual saver description explained in the previous section. Zgrzytor is a simple noise generator using a shift register with EXOR feedback. It is a well known technique for generate periodic sounds (for short register) or pseudorandom noise (for long register). User can specify taps (bits) of the shift register where EXOR gate feeding back the register is connected. Sampling rate of output, output file name and output format can be also specified. Some example Zgrzytor call may be:

Zgrzytor 3 11 22050 '''WAVE BITS=32'''

This will attach EXOR to bits 3 and 11 (bits are counted from feed side and from 1) and generate 5 seconds (time is hardcoded inside program) of noise, set sampling rate to 22.05 kHz and save as 32-bit WAVE (Zgrzytor works with 32-bit integers, so it can produce "real" 32-bit sound). More about Zgrzytor on its homepage. Of course full source code of Zgrzytor is added to the archive.

Reggae tutorial: Saving audio in user selected format

2012-10-08T19:10:24Z

Krashan: /* Saver Control Without GUI */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name) so it can contain multiple arguments. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Applications wanting to log operations done with GUI, or create some undo history can also retrieve the argument string from GUI object with ''MediaGetArgsFromGui()''. It will generate the argument string basing on current gadgets states.

Reggae tutorial: Saving audio in user selected format

2012-10-08T18:58:11Z

Krashan: /* Saver Control Without GUI */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Buffer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

==Saver Control Without GUI==
While the GUI object provided by Reggae for choosing encoder suits most needs of applications, there are cases, where some lower level control is needed. Some examples include (but are not limited to):
* shell commands
* scripting interface
* application log/undo
* applications using fixed output format
This lower level control is implemented as an argument string. This string contains the audio format specification in textual, human readable form, very similar to form of arguments of MorphOS shell commands. In fact Reggae argument string is parsed with the same function as shell arguments, namely ''ReadArgs()'' from ''dos.library''. To say more, even when application builds a Reggae saver chain from GUI, argument string is used internally as an intermediate stage.

How one builds a Reggae saver from an argument string? There is a function in ''multimedia.class'', named ''MediaBuildFromArgsTags()''. It works exactly the same as ''MediaBuildFromGuiTags()'', the only difference is it takes argument string instead of GUI object. But how the argument string looks like? Let's look at a simple example:

WAVE BITS=24

Every Reggae saver specification consists of two parts. The first part is multiplexer class name, just without the ".muxer" extension. It is capitalized here, but Reggae argument strings are case insensitive. The second part is the rest of string (after skipping whitespaces after multiplexer name. In some cases the second part may be empty, as most formats have default values for encoder parameters. For example one can use simply

AIFF

to have data stored as 16-bit AIFF file. Of course every multiplexer has its own set of parameters, described in its autodoc.

Reggae tutorial: Saving audio in user selected format

2012-10-08T17:32:01Z

Krashan: textual control

Reggae tutorial: Saving audio in user selected format

2012-10-04T15:28:41Z

Krashan: /* Memory Bufer as Data Source */

Reggae tutorial: Saving audio in user selected format

2012-10-04T12:41:18Z

Krashan: /* Encoder, Muxer and their Setup */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Bufer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae. To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

Reggae tutorial: Saving audio in user selected format

2012-10-04T12:36:48Z

Krashan: /* Cleanup */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Bufer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae . To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally, MUI stuff is disposed automatically by MUI.

Reggae tutorial: Saving audio in user selected format

2012-10-04T12:35:42Z

Krashan: /* Cleanup */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Bufer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae . To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==
During cleanup application has to close all classes it created and dispose all objects. There are some exceptions however. Once MUI object returned by ''MediaGetGuiTags()'' is added to a MUI application, it need not to be disposed separately. It will be automatically disposed, when MUI ''Application'' object is disposed.

Reggae objects should be disposed in order from output to source:

DisposeObject(writer);
DisposeObject(codec);
DisposeObject(raw_audio);
DisposeObject(stream);

This order is safe even if ''writer'' object is running when being disposed. If the order is not maintained and running chain is being disposed, it is theoretically possible that Reggae accesses already freed memory.

Reggae classes used should be also closed, '''except of classes for muxer and encoder'''. As these classes are automatically opened by Reggae, they are also automatically closed. Then, in the example, only ''memory.stream'', ''rawaudio.filter'' and ''file.output'' classes must be closed by application. To sum it up, what is explicitly opened/created by application, must be explicitly closed/disposed. Anything created automatically by Reggae is handled by Reggae. Finally MUI stuff is disposed automatically by MUI.

Reggae tutorial: Saving audio in user selected format

2012-10-04T10:17:07Z

Krashan: /* Saving Audio */

''Grzegorz Kraszewski''

==Introduction==
Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with ''MMM_Play()'' method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

==Preparing Source Data==
Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of [http://krashan.ppa.pl/articles/u1synth U1Synth]), or by using ''datapush.stream'' class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter [http://krashan.ppa.pl/articles/zormanita Zormanita], which also is opensourced.

Data in a buffer should be in one of Reggae [[Reggae_common_formats|common formats]]. There are three common formats for audio: ''INT16'', ''INT32'' and ''FLOAT32''. The choice depends on purpose and required processing quality. ''INT16'' is the fastest format and is best suited for playback. ''FLOAT32'' has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. ''INT32'' is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via ''memory.stream'' object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with ''MediaAllocVec()'' function of ''multimedia.class''. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 ''INT16'' audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

==Creating Format Selection GUI==
Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to ''MediaGetGuiTagList()'' function. As the name suggests, a [[Taglists|taglist]] can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
MGG_Type, MGG_Type_Muxers,
MGG_Media, MMT_SOUND,
MGG_Selector, MGG_Selector_List,
MUIA_Frame, MUIV_Frame_Group,
MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, ''MMG_Type'' selects type of Reggae classes queried for GUI. There are two possibilities currently. ''MGG_Type_Muxers'' is used when one encodes and saves media stream. There is also ''MGG_Type_Filters'', which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, ''MGG_Media'' defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value ''MMT_SOUND'' makes sure only audio codecs are shown. The third tag, ''MGG_Selector'' influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

<center>[[File:Mediaformat1.png]]     [[File:Mediaformat2.png]]</center>

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI ''Group'' class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some ''MUIA_Group_Child'' tag. In most cases it is created statically at application initialization. ''Zormanita'' and ''U1Synth'' create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

==Building Reggae Processing Chain==
====Memory Bufer as Data Source====
Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of ''memory.stream'' class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with ''rawaudio.filter'' object.

While it looks unnecessarily complicated, it allows for more freedom. By changing ''memory.stream'' to ''file.stream'' one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both ''memory.stream'' and ''rawaudio.filter'' are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
MMA_Stream_Handle, (IPTR)Buffer,
MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the ''MMA_Stream_Length'' attribute takes ''QUAD'' number, it has to be passed via pointer. Length must be specified for ''memory.stream'', as it has no natural end, like for example ''file.stream''. Of course ''memory.stream'' class has to be opened previously with ''OpenLibrary()'', as [[Reggae_tutorial:_Accessing_Reggae_in_applications#Opening_and_closing_individual_classes|described here]].

The next step is ''rawaudio.filter''. Its creation is pretty straightforward:

Object *raw_audio;

raw_audio = NewObject(NULL, "rawaudio.filter",
MMA_Sound_Channels, 1,
MMA_Sound_SampleRate, 44100,
TAG_END);

MediaSetPort(raw_audio, 1, MMA_Port_Format, MMFC_AUDIO_INT16);

Note that audio format is not specified as a tag for object constructor, but is just set for the output port. As the last step in this section, we connect these two objects together:

MediaConnectTagList(stream, 0, raw_audio, 0, NULL);

Stream output is now connected to ''rawaudio.filter'' input.

====Encoder, Muxer and their Setup====
This step is automatically performed by Reggae . To set up the encoder and multiplexer duo, Reggae needs two sources of information:
* GUI object with all selections made by user.
* Source data stream.
Both are provided as arguments to ''MediaBuildFromGuiTags()'' function:

Object *codec;

codec = MediaBuildFromGuiTags(format_selector, raw_audio, 1, TAG_END);

The function does a complex task of setting up media codec. Let's analyse it step by step:
* Reggae checks in the GUI which format has been selected by user. It opens appropriate multiplexer class and creates its instance.
* Based on detailed GUI selections, Reggae determines which encoder will cooperate with multiplexer selected before. Again its class is opened and object created.
* Encoder is connected to the data source passed in arguments (object and port). Encoder parameters are set according to GUI and source data parameters.
* Multiplexer is connected to encoder. Again, multiplexer parameters (if any) are set according to GUI and parameters of stream.
* Both the objects (plus any auxiliary objects Reggae may create silently) are packed into a single compound object and returned as such.
At the end of this step, we have an almost complete and connected Reggae processing chain for saving audio. The output port of ''codec'' is not connected, waiting for writing stream object.

====Data Output====
The last thing we need is an object writing encoded data. In most cases it is ''file.output'' instance. One creates it with following code:

Object *writer;

writer = NewObject(NULL, "file.output",
MMA_StreamName, (IPTR)"somefile",
TAG_END);

In this example the file name is hardcoded, of course it is bad style. For shell based programs the file name comes from commandline arguments, for GUI programs it comes from a filerequester, or MUI ''Popasl'' object. Of course ''file.output'' class accepts complete paths, both absolute (starting with volume name) and relative to the current program directory. After creation, output object is connected with codec output:

MediaConnectTagList(codec, 1, writer, 0, NULL);

Now the whole chain is ready to save data. We just need to pull a trigger...

==Saving Audio==
An object of ''file.output'' class creates a subprocess. All the work related to encoding media and writing it to disk is done by this subprocess. While writing, application is not blocked. Because of this it may be a good idea to disable gadgets triggering media saving for the time of writing.

As saving is asynchronous, there must be a way to notify the application when it is finished. It is done exactly the same way as for [[Reggae_tutorial:_Playing_a_sound_from_file#Waiting_for_end_of_sound|audio playback]], one in fact uses even the same methods. Then we can either get a signal or a reply for a message, when saving is finished. Waiting for such a signal or message may be added to the [[Event_Driven_Programming,_Notifications#The_Ideal_MUI_Main_Loop|MUI event loop]].

Notification on end of saving is usually set before starting it. Minimalistic code in a shell based application may look like this:

DoMethod(writer, MMM_SignalAtEnd, (IPTR)FindTask(NULL), SIGBREAKB_CTRL_C);
DoMethod(writer, MMM_Play);
Wait(SIGBREAKF_CTRL_C);

Note that while ''Wait()'' takes a signal mask, ''MMM_SignalAtEnd()'' takes a signal number. Do not mistake them. Of course such code blocks application for the saving time. More advanced one may for example check progress periodically and display some messages. For example [http://krashan.ppa.pl/articles/zormanita/ Zormanita] updates progressbar while saving.

While saving media may be aborted at any time by executing ''MMM_Stop()'' method on the writer object, it is not recommended. Currently it is only safe for raw format (''rawaudio.muxer''). AIFF and WAVE multiplexers write headers at start and do not update them when writing is stopped. Then aborting the writer will left saved files incomplete, with header values not matching data actually stored. This behaviour may or may not be improved in the future. It is up to the application then to delete such broken files (it also include cases where writing is aborted due to I/O error).

==Cleanup==

Reggae tutorial: Saving audio in user selected format

2012-10-04T09:56:24Z

Krashan: /* Saving Audio */

Reggae tutorial: Saving audio in user selected format

2012-10-04T09:37:54Z

Krashan: /* Data Output */

Reggae tutorial: Saving audio in user selected format

2012-10-04T09:36:30Z

Krashan: /* Data Output */

Reggae tutorial: Saving audio in user selected format

2012-10-04T09:20:29Z

Krashan: /* Encoder, Muxer and their Setup */

Reggae tutorial: Saving audio in user selected format

2012-10-04T09:17:20Z

Krashan: /* Encoder, Muxer and their Setup */

Reggae tutorial: Saving audio in user selected format

2012-10-04T09:01:09Z

Krashan: /* Building Reggae Processing Chain */

Reggae tutorial: Saving audio in user selected format

2012-10-04T08:38:37Z

Krashan: /* Memory Bufer as Data Source */

Reggae tutorial: Saving audio in user selected format

2012-10-04T08:36:21Z

Krashan: /* Memory Bufer as Data Source */

Reggae tutorial: Saving audio in user selected format

2012-10-04T08:36:00Z

Krashan: /* Memory Bufer as Data Source */

Reggae tutorial: Saving audio in user selected format

2012-10-04T08:26:00Z

Krashan: /* Preparing Source Data */

Reggae tutorial: Saving audio in user selected format

2012-10-04T08:11:48Z

Krashan: /* Memory Bufer as Data Source */

Reggae tutorial: Saving audio in user selected format

2012-10-04T08:02:41Z

Krashan: /* Preparing Source Data */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:58:08Z

Krashan: /* Memory Bufer as Data Source */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:43:39Z

Krashan: /* Building Reggae Processing Chain */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:43:00Z

Krashan: /* Building Reggae Processing Chain */ subchapters

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:29:02Z

Krashan: /* Creating Format Selection GUI */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:25:53Z

Krashan: /* Creating Format Selection GUI */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:25:11Z

Krashan: /* Creating Format Selection GUI */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:14:09Z

Krashan: /* Creating Format Selection GUI */

Reggae tutorial: Saving audio in user selected format

2012-10-04T07:10:09Z

Krashan: /* Creating Format Selection GUI */