File: tutorial.html

package info (click to toggle)
yiff 2.14.5-7
links: PTS
area: main
in suites: squeeze
size: 3,384 kB
ctags: 3,360
sloc: ansic: 40,506; cpp: 7,420; makefile: 426; sh: 244
file content (748 lines) | stat: -rw-r--r-- 26,347 bytes
parent folder | download | duplicates (3)
<html>
<head>
<title>YLib Programming Tutorial</title>

<meta name="Author" CONTENT="WolfPack Entertainment">
<meta name="description" CONTENT="YLib Programming Tutorial">
<meta
name="keywords" CONTENT="Y2,YIFF,YLib,libY,Sound,Server,system,documentation,
tutorial,programming,program">
<meta name="GENERATOR" CONTENT="Mozilla/3.04Gold (Linux; I) [Netscape]">

<body
 background=""
 bgcolor=ffffff
 text=000000
 link=c050cf
 vlink=80708f
 alink=606060
>

</head>


<body>
<a name="top">
<left>
<p><h6>
Back to <a href="documentation.html">documentation</a>
</h6></p>
<p><h6>
2000 December 1
</h6></p>

</left>
<center>
<h1>YLib Programming Tutorial</h1>
</center>

<left>
<h3>Contents</h3>
<ol>
 <li><a href="#s1">Introduction</a>
 <li><a href="#s2">Hello World in YLib</a>
 <li><a href="#s3">YLib Procedure</a>
 <li><a href="#s4">Putting It All Togeather</a>
 <li><a href="#s5">YEvent Handling</a>
</ol>
</left>



<left>
<img src="hr1.gif" width=95% height=32>
<a name="s1">
<h2>Introduction</h2>
<p>
Y Sound Systems is a <i>low-level</i> and <i>multi-client</i> system of
access
to a machine's <i>Recorder</i> (sound card). YLib is the <i>programming
language</i> used to write applications for that system. YLib follows
the <a href="http://www.x.org/">X window Systems</a> pattern of
design and is licensed under GPL (GNU Public License).
</p>

<p>
You can develop open software, free software, or even commercial
(non-free) software using YLib without having to spend anything for
licenses or royalties.
</p>

<p>
The YLib is intended for (but <b>not</b> limited to) entertainment
software, any application that wants simplified, multiple,
network transparent access to the <i>Recorder</i> much like multiple GUI
applications want to output to the display, should use YLib.
</p>

<p>
YLib attempts to follow as <u>many existing standards as possible</u>,
many of its <i>objects</i> contain data that are formatted after popular
formats such as the <i>DSP Sound Object</i> capable of having
raw, voc, or wav formats.
</p>

<h6>
Back to the <a href="#top">top</a>.
</h6>
</left>



<left>
<img src="hr1.gif" width=95% height=32>
<a name="s2">
<h2>Hello World in YLib</h2>

<p>
First make sure that you have access to a <i>Y Server</i> 
(preferably on your <b>own</b> computer) and that YLib
(which consists of <code>/usr/lib/libY2.so.#</code> and
(<code>/usr/include/Y2/*</code>) is
properly installed. If not, then you should obtain the
complete package of the YIFF Sound System (both server and library)
<a href="download.html">here</a> and install it. Get the
<b>latest</b> version and make sure that you build and install
all the compoents to maximize your Y Sound System capabilities.
</p>

<a name="helloworld">
<p>
We begin our journey into YLib with a simple hello world(tm) program
(note, the below source comes from the YIFF source package, from
the file <code>yiffutils/helloworld.c</code>). Code colored
<font color=ff0000>red</font> in the below example denotes code
that is <b>specific</b> to the YLib language.
</p>

<p><pre><code><font color=000000>
#include &lt;stdio.h&gt;

<font color=ff0000>#include &lt;Y2/Y.h&gt;</font>           /* Basic Y types and constants. */
<font color=ff0000>#include &lt;Y2/Ylib.h&gt;</font>        /* YLib functions and structs. */

/* Change this to the address and port of the Y server you want
 * to connect to. Note that 127.0.0.1 is a symbolic address
 * meaning `localhost'.
 */
<font color=ff0000>#define CON_ARG             "127.0.0.1:9433"</font>


int main(int argc, char *argv[])
{
<font color=ff0000>        YConnection *con;</font>
        char *filename;
<font color=ff0000>        YEventSoundObjectAttributes sndobj_attrib;</font>
<font color=ff0000>        YID play_id;</font>
<font color=ff0000>        YEvent event;</font>


        /* Need atleast one argument, being the file name.
         * This is so that we can play a sound object on file.
         */
        if(argc < 2)
                return(1);
        else
                filename = argv[1];


        /* Connect to the Y server. We pass NULL as the start
         * argument, this means the Y server will not be started if
         * it was detected to be not running. The connection
         * argument is CON_ARG which is defined at the beginning of
         * the source. The connection argument is a string of the
         * format "<addr>:<port>".
         */
<font color=ff0000>        con = YOpenConnection(
                NULL,
                CON_ARG
        );</font>
<font color=ff0000>        if(con == NULL)</font>
        {
                /* Failed to connect to the Y server. */
<font color=ff0000>                fprintf(
                        stderr,
                        "%s: Cannot connect to YIFF server.\n",
                        CON_ARG
                );</font>
                return(1);
        }


        /* Check if the filename exists on the machine that
         * the Y server is running on and obtain its attributes.
         */
<font color=ff0000>
        if(YGetSoundObjectAttributes(
                con,
                filename,
                &sndobj_attrib
        ))</font>
        {
                /* Can't get sound object attributes. */
<font color=ff0000>                fprintf(
                        stderr,
                        "%s: Error: Missing or corrupt.\n",
                        filename
                );</font>
        }
        else
        {
                /* Start playing the sound object. */
<font color=ff0000>                play_id = YStartPlaySoundObjectSimple(
                        con,
                        filename
                );</font>
<font color=ff0000>
                /* There is also a YStartPlaySoundObject()
                 * function which allows additional specified
                 * values for playing. More on that later.
                 */
</font>
                /* Print sound object attributes. */
<font color=ff0000>                switch(sndobj_attrib.format)
                {
                        case SndObjTypeDSP:
                        printf(
 "ID: %i  Type: DSP  SmpRate: %i Hz  Bits: %i  Ch: %i\n",
                            play_id,
                            sndobj_attrib.sample_rate,
                            sndobj_attrib.sample_size,
                            sndobj_attrib.channels
                        );
                        break;

                        case SndObjTypeMIDI:
                        printf(
 "ID: %i  Type: MIDI\n",
                            play_id
                        );
                        break;

                        default:
                        printf(
 "ID: %i  Type: *Unknown*\n",
                            play_id
                        );
                }</font>

                /* Manage events: Wait untill audio is done playing.
                 * Here we call YGetNextEvent() repeatedly to get
                 * events from the Y server.  Once we get an event
                 * we process it accordingly by its type.
                 */
                while(1)
                {
                        /* Get the next event (if any). */
<font color=ff0000>                        if(YGetNextEvent(
                                con,
                                &event,
                                False   /* Nonblocking. */
                        ) > 0)
                        {
                                /* Sound object stopped playing? */
                                if((event.type == YSoundObjectKill) &&
                                   (event.kill.yid == play_id)
                                )
                                {
                                        /* Our play has stopped. */
                                        printf("Done playing.\n");
                                        break;
                                }
                                /* Server disconnected us? */
                                else if(event.type == YDisconnect)
                                {
                                        /* Got disconnected. */
                                        printf(
                         "Y server disconnected us, reason %i.\n",
                                            event.disconnect.reason
                                        );

                                        /* Need to close connection! */
                                        YCloseConnection(con, False);
					con = NULL;
                                        break;
                                }
                                /* Server shutdown? */
                                else if(event.type == YShutdown)
                                {
                                        /* Server shutdown. */
                                        printf(
                                   "Y server shutdown, reason %i.\n",
                                            event.shutdown.reason
                                        );

                                        /* Need to close connection! */
                                        YCloseConnection(con, False);
                                        con = NULL;
                                        break;
                                }
                                else
                                {
                                        /* Some other Y event, ignore. */
                                }
                        }</font>

                        usleep(1000);   /* Don't hog the CPU. */
                }
        }


        /* Disconnect from the Y server. We need to pass the
         * original connection pointer con to close that
         * connection to the Y server. Note that con may be
         * NULL at this point if the Y server disconnected us
         * already, passing NULL is okay.
         *
         * The second argument asks us do we want to leave the
         * Y server up when we disconnect. If we were the
         * program that started the Y erver and the second
         * argument is set to False then the Y server will
         * be automatically shut down.  To ensure that the Y
         * server stays running, you can pass True instead.
         */
<font color=ff0000>        YCloseConnection(con, False);
        con = NULL;</font>


        return(0);
}
</font></code></pre>
</p>

<p>
To compile the program, type:
<ul><li><code>
cc helloworld.c -o helloworld -lY2
</code></ul>
</p>

<p>
The <code>-lY2</code> instructs the compiling procedure to link
to <code>libY2.so.#</code> (where <code>#</code> is the version
number of YLib.
</p>

<p>
Now <font color=ff0000>before</font> you run <code>helloworld</code>, make
sure that you have:
<ol>
 <li>A Y server running on (preferably) your computer
(to run YIFF type <code>/usr/sbin/yiff /etc/yiff/yiffrc</code>).
 <li>The Y utility programs compiled and installed (on <b>your</b> computer).
 <li>A readable raw, voc, or wav file to play on the <u>computer the Y
server is running on</u>.
</ol>
If all of the above requirements are met, then type the following
commands:
<ol>
 <li><code>yrecinfo -m</code> (to get a list of Audio modes).
 <li><code>yset audio &lt;audio_mode_name&gt;</code> (choose an Audio mode
that best suits the sound file you are about to play).
 <li><code>./helloworld /home/me/helloworld.wav</code> (play it).
</ol>
You should be hearing the sound file being
played. If the sound didn't come out right, then you may need to select
another Audio mode that better matches the sound file you were trying to
play (<code>yrecinfo -m</code> to get a list of Audio modes) or adjust
the Y mixers (use <code>ymixer</code>).
</p>

<p>
Now is a good time to review the <a href="#helloworld">helloworld</a>
program.
You may have noticed that its code is awefully long for a `simple
example',
this is because Ylib is a <i>low-level</i> language.
<i>Low-level</i> languages are very lengthy, however the advantage is
that they provide the most functionality to the actual device you want to
control.
</p><p>
Now don't give up just yet, there's <b>good</b> news ahead! You now have
been
exposed to all the basic and some intermediate levels of code that's
required to
work with Ylib. It also means that since you made it this far,
you're over the first and most difficult hurdle. If you keep at it, then
you
are gauranteed to understand the rest of YLib!
</p><p>
You'll find out that the `massive lines of required code' are a blessing
rather
than `make work'.
It allows you to control as much of the aspect of sound programming while
keeping the even more low level coding hidden (yup, you don't want a back
stage
tour just yet!) and keeping your code portable to any platform with YLib.
</p><p>
<u>Remember that any platform with BSD style networking (ie, all UNIXes)
can support YLib</u> but not always the Y server. This means you can
write your programs for almost any platform and not have to worry about
portability, because YLib is almost gauranteed to be portable to it.
</p><p>
If a Y server is not available for that platform, YLib will simply return
a NULL when you call <code>YOpenConnection()</code> and your program
should be able to continue on normally without playing sound.
</p>

<p>
There is also a more <b>advanced</b> form of
<code>YStartPlaySoundObjectSimple()</code> which allows you to
specify additional values on how your Sound Object should be
played (these values can also be adjusted while the Sound Object is being
played).
</p>

<p>
<pre><code><font color=000000>
        YEventSoundPlay value;
        YID yid;

        value.flags = YPlayValuesFlagPosition |
                      YPlayValuesFlagTotalRepeats |
                      YPlayValuesFlagVolume |
                      YPlayValuesFlagSampleRate;
        value.position = 0;
        value.total_repeats = total_repeats;    /* Can be -1. */
        value.left_volume = vol_left;           /* 0.0 to 1.0. */
        value.right_volume = vol_right;         /* 0.0 to 1.0. */
        value.sample_rate = sample_rate;        /* In Hz, can be 0. */

        yid = YStartPlaySoundObject(con, path, &value);
</font></code></pre>
</p>

<p>
In the <code>YEventSoundPlay value</code> the member
<code>flags</code> specify which values are to be changed.
The <code>position</code> specifies which byte position to start playing
at.  If the Audio is in 16 bits, make sure the position is an even number.
<code>total_repeats</code> specify how many times you want to repeat this
play, normally it is set to 1 or -1. -1 means to repeat infinatly.
The <code>left_volume</code> and <code>right_volume</code> specify the
volume of the Sound Object to be mixed into the Sound, valid values are
from 0.0 to 1.0 (inclusive). The <code>sample_rate</code> specifies
the applied sample rate deviance of the Sound Object to be played at in
Hz, specifying a value less than the actual sample rate of the current
Audio has no affect (hence passing 0 is the default), specifying a value
greater than will make the Sound Object play faster (good for engine
sound simulations).
</p>
<p>
Try replacing the call to <code>YStartPlaySoundObjectSimple()</code>
in the sample source with the above example of
<code>YStartPlaySoundObject()</code>. Try tinkering with the values
passed on to <code>YStartPlaySoundObject()</code> and see what happens!
</p>

<h6>
Back to the <a href="#top">top</a>.
</h6>
</left>


<left>
<img src="hr1.gif" width=95% height=32>
<a name="s3">
<h2>YLib Procedure</h2>
<p>
Good news, it's time to simplify things!
</p><p>
Now that you've seen an example program, all you need to do next is pick
out
the significant parts of it... that we'll be covering in this section.
</p><p>
YLib is a low level language because it requires the calling program to
handle all the procedures (except timings to the sound driver, since YLib
is async), while
at the same time YLib is a high-level language because it has a
transparent
network layer and uses a server to do all the messy sound loading, mixing,
and playing.
</p><p>
Let's simplify the low level part first, the following is the procedure
(flow) of YLib.  Note the sequence of YLib functions your program needs
to call:
<ol>
 <li><code>YOpenConnection()</code> this opens a connection to the Y
server
and (at your option) starts it too. You call this function once when your
program wants to connect to the Y server (usually at startup or when your
program wants to turn on sound).
 <li><code>YGetNextEvent()</code> this is considered the <i>maintainance
function</i> as well as the event reporter. You need to call this function
<u>each time your program loops</u> (note the
<a href="#helloworld">helloworld</a>
example does not illustrate this well, we'll go into depth about this
function later).
 <li><code>YCloseConnection()</code> this closes the connection to the Y
server
and (at your option) if your program started the Y server, then it will
shut down
the Y server.
</ol>
</p><p>
Let's talk about <code>YOpenConnection()</code> first. This function
when called, returns a pointer that you will use as refferance to the
connection to the Y server when using most of the other YLib functions.
Later on, before your program exits you will want to call
YCloseConnection()
and pass this pointer to it.  Once you do that the pointer is <u>no longer
valid</u> and your connection to the Y server should be considered closed.
If you want to connect to the Y server again, just call
<code>YOpenConnection()</code> again and you will get a pointer to the new
connection.
</p><p>
Next is the more complicated function <code>YGetNextEvent()</code>.
This function has two purposes, it serves as a <i>maintainance
function</i>
(something to allow YLib to do internal things you don't need/want to
worry
about) and fetches the latest event (if any) comming from the Y server.
It's up to your program to handle these events properly, examples about
handling events from <code>YGetNextEvent()</code> will be covered later.
The important part is that your program <u>call this function atleast once
per loop</u> (example on that is comming, when we put it all togeather).
</p><p>
Lastly is <code>YCloseConnection()</code> which closes the connection
to the Y server. You need to pass it the pointer that you got from
<code>YOpenConnection()</code>, or if you pass NULL then it will do
nothing.
</p>

<h6>
Back to the <a href="#top">top</a>.
</h6>
</left>



<left>
<img src="hr1.gif" width=95% height=32>
<a name="s4">
<h2>Putting It All Togeather</h2>
<p>
Now it's time to get a contrasting overview of
how and where <b>your</b> program should call YLib functions
(note this example may differ with the
<a href="#helloworld">helloworld</a> example):
</p>

<p>
<pre><code><font color=000000>
#include &lt;Y2/Y.h&gt;           /* Basic Y types and constants. */
#include &lt;Y2/Ylib.h&gt;        /* YLib functions and structs. */
#include "myprogram.h"

YConnection *con;

int main()
{
        YEvent event;


        MyProgramInitialize();
        con = YOpenConnection(NULL, somewhere);
        if(con == NULL)
                return(1);

        while(1)
        {
                MyProgramManage();
                if(YGetNextEvent(con, &event, False) > 0)
                        MyProgramHandleEvent(&event);
        }

        MyProgramShutdown();
        YCloseConnection(con);

        return(0);
}
</font></code></pre>
</p>

<p>The above sample code is not compilable because it is missing
the functions <b>you</b> will have to write for your program.
Instead, pay attention to the procedure and note the following:
</p><p>
Notice how <code>YOpenConnection()</code> is called once at the very
beginning and <code>YCloseConnection()</code> is called at the end.
</p><p>
Also notice how <code>YGetNextEvent()</code> is called once per loop,
and if there was a new event then it would be passed on to be handled
by your program's function <code>MyProgramHandleEvent()</code>.
</p><p>
Those are the key points you want to pay attention to, remember that YLib
is async.  It's not too important when you call the YLib function, it's
important <u>what order</u> you call them (hence why we emphisize
procedure).
</p>

<h6>
Back to the <a href="#top">top</a>.
</h6>
</left>


<left>
<img src="hr1.gif" width=95% height=32>
<a name="s5">
<h2>YEvent Handling</h2>

<p>Here we show you how to handle YEvents obtained from
<a href="manual.html#s4"><code>YGetNextEvent()</code></a>
by example.
</p><p>
Below is what your <code>MyProgramHandleEvent()</code> function probably
should look like (that function came from the previous section
<a href="#s4">Putting It All Togeather</a>).
</p>

<p><pre><code><font color=000000>
void MyProgramHandleEvent(YEvent *event)
{
        if(event == NULL)
                return;


        switch(event->type)
        {
                /* Audio mode has changed, this happens sometimes.
                 * usually when your program or another program has
                 * asked the Y server to change Audio modes.
                 *
                 * When this happens all your Sound Objects that
                 * you have playing (if any) will recieve
                 * YSoundObjectKill events.
                 */
                case YAudioChange:
                if(event->audio.preset)
                        printf(
        "Audio mode changed to `%s'.\n",
                                event->audio.mode_name
                        );
                else
                        printf("Audio mode changed.\n");
                        printf("Sample Rate: %i Hz\n",
                                event->audio.sample_size
                        );
                        printf("Channels: %i  Bits: %i\n",
                                event->audio.channels,
                                event->audio.sample_size
                        );
                        printf("Fragment Size: %i Bytes\n",
                                event->audio.fragment_size_bytes
                        );
                break;

                /* The Audio cycle interval on the Y server has changed,
                 * either by your program or another program.
                 */
                case YCycleChange:
                printf("Audio cycle interval changed to: %ld ms\n",
                        event->cycle.cycle_us
                );
                break;

                /* Your program has been disconnected from the Y server.
                 * A variety of reasons may have caused this but
                 * regardless of that, you must set the YConnection
                 * pointer you got from YOpenConnection() to NULL.
                 */
                case YDisconnect:
                printf("You have been disconnected, reason code %i.\n",
                        event->disconnect.reason
                );
                /* Need to close connection afterwards. */
                YCloseConnection(con, False);
                con = NULL;
                break;

                /* A host has been added or removed, this isn't
                 * a very important event unless your program is serious
                 * about managing who's allowed to connect.
                 */
                case YSetHost:
                printf("Host %i.%i.%i.%i has been %s.\n",
                        event->host.ip.charaddr[0],
                        event->host.ip.charaddr[1],
                        event->host.ip.charaddr[2],
                        event->host.ip.charaddr[3],
                        ((event->host.op) ? "added" : "removed")
                );
                break;

                /* A sound object (that your program instructed to
                 * play) has stopped playing. This may be important
                 * if you want to keep track of when a sound object
                 * has stopped playing (if not then just ignore it).
                 */
                case YSoundObjectKill:
                printf("Sound object YID %ld has stopped playing.\n",
                        event->kill.yid
                );
                break;

                /* A mixer channel value has changed. This is usually
                 * not very important and you can ignore it.
                 */
                case YMixerChannel:
                printf("Mixer %i has changed value to %.4lf %.4lf\n",
                        event->mixer.code,
                        ((YMixerValues >= 1) ? event->mixer.value[0] : 0),
                        ((YMixerValues >= 2) ? event->mixer.value[1] : 0)
                );
                break;

                /* The Y server has shut down, treat this event
                 * as if it were a YDisconnect type event.
                 */
                case YShutdown:
                printf("Y server has shut down, reason code %i.\n",
                        event->shutdown.reason
                );
                /* Need to close connection afterwards. */
                YCloseConnection(con, False);
                con = NULL;
                break;
        }
}
</font></code></pre>
</p>

<p>Most of the events can be ignored for a simple Ylib program. There
are only two <i>very</i> important events that you <b>must</b> watch for,
they are
<code>YDisconnect</code> and <code>YShutdown</code>. When you
recieve either of those events you must call
<code>YCloseConnection()</code> and then set the connection pointer to
<code>NULL</code>. Those events indicate that the Y server has either
disconnected you or it has shut down.
</p><p>
Another important responsibility on your part is to make sure that
you call <code>YGetNextEvent()</code> to allow it to manage itself
and flush the event queue. This does not need to be called on every
loop but atleast reasonably often enough to ensure that the Ylib side
of things are kept reasonably up to date.
</p>




<p>This is the end of the current YLib tutorial, we hope that you've had a
productive and educating experiance and wish you the best of luck with
YLib!
</p><p>
If you feel that there is a topic that should be included, please write
to the <a href="http://wolfpack.twu.net/contacts.html">developers</a>.
</p>


<h6>
Back to the <a href="#top">top</a>.
</h6>
</left>


</body>
</html>