-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
171 lines (127 loc) · 6.67 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
Welcome to PBRocket
===================
Update: here's a short YouTube video showing a demo and the editor
side by side: https://www.youtube.com/watch?v=Sb34lU7c4KU
PBRocket - a PureBasic port of GNU Rocket - is a sync-tracker, a tool for
synchronizing audio and visuals in demoscene productions. It consists of a
library (a single PB include file) that can either communicate with a GUI
editor through a network connection, or play back an exported data-set.
The GUI editor has also been ported to PureBasic, but lacks a few features.
The original GUI editor (compiled from GNU Rocket sources) is also available
in the Downloads folder.
The editor is laid out like a music-tracker: tracks (columns) and rows.
In a music-tracker, each track represents... a track, and each row
represents the smallest division (step) of a measure (or bar). In PBRocket,
each track represents a separate "variable" in the demo over the entire time-
domain of the demo. Each row represents a specific point in time, and each
row holding a value becomes a keyframe. The values between two keyframes are
interpolated over time according to their interpolation modes.
Typically, you will tell PBRocket the tempo of your tune, how many rows per
beat you want to use, and the names of the variables you want it to
synchronize in your demo. Once this is done, the Sync Editor will create an
empty track for each of the variables. These variables can be anything you
can think of: camera positions, 3D objects rotations and translations, RGB
values, scene change triggers for your scene manager, speed values for your
oldskool text scroller, and so on.
How does it work?
-----------------
PBRocket can be run in Edit mode or Player mode.
In Edit mode, PBRocket communicates with the Sync Editor using a network
connection in a slave/master fashion: any edit in the Sync Editor (key
values, row position and play/pause state) is immediately sent to PBRocket
and becomes instantly visible. All the data edited in the Sync Editor can be
saved to disk (for further editing) or exported to individual track-data
files.
In Player mode, PBRocket will load all the data in memory (either by reading
the exported track-data files from disk or from a DataSection) and will
replay them in sync with the audio automatically, without the need to be
connected to the Sync Editor.
Ok, how do I start?
-------------------
Just have a look at the included examples, they're rather self-explanatory.
Nonetheless, here is a short description of the process:
1. Define a #RKT_SYNC_PLAYER constant with a value of 0 to run PBRocket in
Edit mode. (You'll obviously want to start in Edit mode since all
variables are set using the Sync Editor)
2. Include PBRocket.pbi (or PBRocket_BASS.pbi) in your main program.
3. Load an audio file and create an audio callback device, using your audio
file's identifier, the BPM of the audio file, and the RPB you want to use.
For instance, a BPM (beats per minute) of 120 and an RPB (row per beat)
value of 8 will give you a resolution of 960 (120*8) keyframes per
minute, or 16 keyframes per second.
This audio callback device will be used by the sync device to get (in
both modes) and set (in Edit mode) the current replay position of your
demo.
4. Create a sync device. The sync device is used to create/retrieve tracks,
add/delete/modify keyframes values, and retrieve the value of the
synchronized variables for the current row.
5. Define the variables you want to synchronize and create a track for each
of them. The Sync Editor will either create new empty tracks if they
don't exist in the current rocket file (or if no rocket file was loaded)
or it will start sending previously defined keyframes to the demo if they
already exist in the currently loaded rocket file.
6. Start playing the audio file, and enter the main loop of your demo.
7. Inside your main loop, retrieve the current value of each of your
variables and use it as you wish. In Edit mode, you'll also need to
update your sync device to let PBRocket process events from the Sync
Editor.
8. When your demo is over (window is closed), just free your sync device
and you're done.
Running the example
------------------
Open the PureBasic editor and load example.pb from the location where you
extracted PBRocket archive.
Run sync_editor.exe. If it's the first time you run it, your firewall will
probably ask you if you want to grant Sync Editor access to the network,
answer yes.
Load the stars.rocket file in Sync Editor.
Compile and run example.pb. Sync Editor will send all keyframes to the demo
program.
Make Sync Editor the active window (click it anywhere) and use the UP and
DOWN arrow keys to change the current row. You should see changes happen in
real time in your demo program.
Now move the cursor all the way up the tracks to row 0 then press the
spacebar on your keyboard. The demo will start playing. Press the spacebar
again to pause it.
Using a different audio library
===============================
PBRocket comes in two flavours, yes sir! PBRocket.pbi uses the default
PureBasic Sound library and PBRocket_BASS.pbi uses BASS, the audio library
from un4seen. BASS itself and the PB API can be downloaded from
http://www.un4seen.com. You'll need to put bass.dll and c/bass.lib in the
example directory. However, if you insist on using a different audio library
you'll need to modify three procedures and adapt them according to your
audio library's API.
Procedure.d RKT_audio_get_row(*this.audio_cb)
; use *this\stream as the reference to your audio stream
; you'll need to return the play position in seconds * *this\rowrate
; (in Edit mode, round it up a bit to be visually in sync with the editor)
Protected pos.d = getYourSoundPositionInSecs()
CompilerIf #RKT_SYNC_PLAYER
ProcedureReturn (pos * *this\rowrate)
CompilerElse
ProcedureReturn (pos * *this\rowrate) + 0.05
CompilerEndIf
EndProcedure
Procedure RKT_audio_set_row(*this.audio_cb, row.i)
; use *this\stream as the reference to your audio stream
; you'll need to set the play position at row / *this\rowrate
getYourSoundPositionInSecs(row / *this\rowrate)
EndProcedure
Procedure RKT_audio_pause(*this.audio_cb, flag.i)
; use *this\stream as the reference to your audio stream
If flag
*this\isPlaying = #False
PauseYourSound()
Else
*this\isPlaying = #True
ResumeYourSound()
EndIf
EndProcedure
If you want to find how many rows are needed for your song, modify this:
Procedure RKT_audio_rows(*this.audio_cb)
; use *this\stream as the reference to your audio stream
ProcedureReturn Round(getYourAudioLength(), #PB_Round_Up) * *this\rowrate
EndProcedure
Have fun!
---------