DEVELOPERS.README
1Using routines in a production/demo/game etc
2--------------------------------------------
3
4- the essence/gutts of the playback routines are in the following files.
5So firstly, copy them over to your source code directory:
6
7COPYING -> COPYING.FunktrackerGOLD
8INSTALL -> README.FunktrackerGOLD
9dsp_mixxer.c
10dsp_mixxer.h
11funkload.c
12funkload.h
13funktracker.c
14funktracker.h
15funktracker_defs.h
16options.h
17
18
19- Then write a playback routine for your song. There are two ways you can
20implement playback- either in foreground as a program, or threaded
21(background).
22
23- For games like Nighthawk (an X11 game i maintain, my recommendation (and
24most game/demo writters of Linux X/Svgalib do this), is to contain your
25effects and playback code in a separate program, and have your main game
26program talk to it via a pipe: issuing playback and effects commands to it
27via the pipe. In this instance, the routines run as foreground:
28
29---$-------------
30.
31.
32#include "funktracker_defs.h"
33#include "dsp_mixxer.h"
34#include "funktracker.h"
35#include "funkload.h"
36
37int main(....)
38{
39 /*This value is 128, which is the maximum patterns for the format.
40 you may like to optimise this for the particular song (songs) you are
41 playing.*/
42 funk_info.funk_pd_size = MAXIMUM_PATTERNS;
43
44 /*Opens up the /dev/dsp device, and configures it's output.
45
46 set these as required:
47
48 sample_rate........... Output sampling rate from 6000 to 44100
49 sample_precision ..... 8 or 16 bit precision (values 8 or 16)
50 stereo_flag ........ 0 for mono, 1 for stereo
51 */
52 if(open_dsp(,
53 <sample_rate>,
54 <sample_precision>,
55 <stereo_flag>))
56 {
57 load_funk_module("song.fnk");
58 if(ferr_val == FERR_OK)
59 {
60 funk_info.trek_status = PLAY;
61 funk_init_for_play();
62 while(funk_info.trek_status == PLAY)
63 {
64 /*the thing that runs the playback routines, mixxes the channels and
65 sends the output to /dev/dsp*/
66 virtualmixxer();
67
68 /*put your pipe mechanics code is in here. You can have a look
69 at my Nighthawk source code to see how i did this if you like.*/
70 }
71 }
72 dealloc_funk_mem();
73 }
74 close_dsp();
75 return 1;
76}
77
78---$-------------
79
80- For pthreads, (that this funktracker distribution uses): we can
81implement it as follows:
82
83---$-------------
84.
85.
86#include <pthreads.h>
87#include "funktracker_defs.h"
88#include "dsp_mixxer.h"
89#include "funktracker.h"
90#include "funkload.h"
91
92void *bg_loop(void *arg)
93{
94 while(funk_info.trek_status == PLAY)
95 virtualmixxer();
96 return NULL;
97}
98
99int main(....)
100{
101 funk_info.funk_pd_size = MAXIMUM_PATTERNS;
102 if(open_dsp(,
103 <sample_rate>,
104 <sample_precision>,
105 <stereo_flag))
106 {
107 load_funk_module("song.fnk");
108 if(ferr_val == FERR_OK)
109 {
110 pthread_t th_a;
111
112 funk_info.trek_status = PLAY;
113 funk_init_for_play();
114 if(pthread_create(&th_a,NULL,bg_loop,NULL) == 0)
115 {
116 void *retval;
117
118 while(funk_info.trek_status == PLAY)
119 {
120 /* do foreground processing in here*/
121 }
122 pthread_join(th_a,&retval);
123 }
124 }
125 dealloc_funk_mem();
126 }
127 close_dsp();
128 return 1;
129}
130
131---$-------------
132
133- Nb/ the reason why i didn't use pthreads in the game is because X
134pthreads seems to upset X11 causing X11 to halt the program (probably use
135to two processes sharing a display id etc). Nb/ that pthreads is safe for
136curses applications. It's highly likely that it's safe for SVgalib
137programs as well.
138
139- include or incorporate options.h into your own header files of your
140game/makefile etc
141
142- if you do use these routines please credit funktracker and me. thanks.
143
144
145:Jason Nunn
146