README.md
1# retroluxury
2
3**retroluxury** is a game library (wannabe) built on top of the [libretro](http://www.libretro.com/) API. It provides functions to blit images to the frame buffer, and to play [PCM audio](http://en.wikipedia.org/wiki/Pulse-code_modulation) and [Ogg Vorbis](http://en.wikipedia.org/wiki/Vorbis) files.
4
5On top of that, **retroluxury** provides higher level functions to deal with sprites and draw maps created with the [Tiled](http://www.mapeditor.org/) map editor.
6
7## API
8
9### Background
10
11The background is a 2D array of 16-bit pixels which represent what is seen on the screen. It's usually called **framebuffer**.
12
13* `int rl_backgrnd_create( int width, int height )`
14
15Creates a framebuffer of `width` by `height` 16-bit pixels. Returns `0` on success or `-1` on error (which can only mean a memory allocation error for now.)
16
17* `void rl_backgrnd_destroy( void )`
18
19Releases the memory allocated by the `rl_backgrnd_create` function.
20
21* `void rl_backgrnd_clear( uint16_t color )`
22
23Clears the entire framebuffer to the given color. The 16-bit color can be calculated from 8-bit red, green and blue values with the following code:
24
25 int r = r * 31 / 255;
26 int g = g * 63 / 255;
27 int b = b * 31 / 255;
28 uint16_t color = ( r << 11 ) | ( g << 5 ) | b;
29
30
31* `void rl_backgrnd_scroll( int dx, int dy )`
32
33Scrolls the framebuffer by the given pixels. `dx` scrolls horizontally, and `dy` scrolls vertically. `rl_backgrnd_scroll( 0, -1 )` scrolls the framebuffer one pixel up.
34
35`rl_backgrnd_scroll` doesn't do anything with lines "created" by the scroll. I.e., if you scroll the framebuffer one pixel left, the last column on the right will contain garbagge. It's up to the application to draw meaningful pixels in these places after a scroll.
36
37* `uint16_t* rl_backgrnd_fb( int* width, int* height )`
38
39Returns a pointer to the top-left pixel of the framebuffer, along with its width and height. Note that the framebuffer can have lines greater than `width` pixels (usually called *pitch*.) To calculate how much pixels to add to a pointer to the framebuffer in order to go one line down, use `width + RL_BACKGRND_MARGIN`.
40
41### Images
42
43Images are collections of [run-length encoded](http://en.wikipedia.org/wiki/Run-length_encoding) pixels, that can be drawn onto the framebuffer. Images also provide means to save the framebuffer pixels that are overwritten when they're drawn, and to restore those saved pixels back to framebuffer afterwards. This scheme allows for higher level contructions such as sprites.
44
45Images have per-pixel transparency of 0, 25, 50, 75 and 100%.
46
47* `rl_image_t* rl_image_create( const void* data, size_t size )`
48
49Creates and returns an image based on the given data. This data can be created with the `rlrle.lua` tool.
50
51* `rl_image_destroy( image )` (macro)
52
53Frees the given image.
54
55* `rl_imageset_t* rl_imageset_create( const void* data, size_t size )`
56
57Creates a collection of images (imageset) from the given data.
58
59* `void rl_imageset_destroy( const rl_imageset_t* imageset )`
60
61Frees the given imageset.
62
63* `void rl_image_blit_nobg( const rl_image_t* image, int x, int y )`
64
65Drawn an image to the framebuffer at position (x, y). `rl_image_blit_nobg` doesn't save overwritten pixels on the framebuffer, so it's kind of a permanent operation, which will be visible on the screen until you overwrite the image with something else, i.e. by clearing the framebuffer.
66
67* `uint16_t* rl_image_blit( const rl_image_t* image, int x, int y, uint16_t* bg )`
68
69Save as `rl_image_blit_nobg`, but saves overwritten pixels on the framebuffer to the `bg` pointer. Make sure you allocate at least `image->used * sizeof(uint16_t)` bytes to `bg`.
70
71* `void rl_image_unblit( const rl_image_t* image, int x, int y, const uint16_t* bg )`
72
73Restores the framebuffer as it was before the image was drawn. The `bg` argument should be the same as the `rl_image_blit` call.
74
75### Tiles
76
77Tiles are similar to images, but they are always a rectangular block of 100% opaque pixels.
78
79* `rl_tileset_t* rl_tileset_create( const void* data, size_t size )`
80
81Creates a tileset (a collection of tiles having the same width and height) from the given data. Each tile is identified by its 0-based index in the tileset.
82
83* `rl_tileset_destroy( tileset)` (macro)
84
85Destroys the tileset.
86
87* `void rl_tileset_blit_nobg( const rl_tileset_t* tileset, int index, int x, int y )`
88
89Similar to `rl_image_blit_nobg`, but draws the tile identified by `index` in the given tileset.
90
91* `uint16_t* rl_tileset_blit( const rl_tileset_t* tileset, int index, int x, int y, uint16_t* bg )`
92
93Similar to `rl_image_blit`.
94
95* `void rl_tileset_unblit( const rl_tileset_t* tileset, int x, int y, const uint16_t* bg )`
96
97Similar to `rl_image_unblit`.
98
99* `void rl_tile_blit_nobg( int width, int height, const uint16_t* pixels, int x, int y )`
100
101Similar to `rl_image_blit_nobg`, but draws a rectangular array of `width` times `height` pixels located at `pixels`.
102
103* `uint16_t* rl_tile_blit( int width, int height, const uint16_t* pixels, int x, int y, uint16_t* bg )`
104
105Similar to `rl_image_blit`.
106
107* `void rl_tile_unblit( int width, int height, int x, int y, const uint16_t* bg )`
108
109Similar to `rl_image_unblit`.
110
111### Sound
112
113**retro luxury** supports stero, 44,100 Hz audio. All audio must be supplied at 44,100 Hz. Mono audio will be duplicated in both left and right channels.
114
115Sounds are just PCM data which are mixed toghether. The `RL_MAX_VOICES` macro defines at compile time how much sounds can be played at the same time (usually called *voices*.) One Ogg Vorbis file can be played in addition to the voices.
116
117* `void rl_sound_init( void )`
118
119Initializes internal data.
120
121* `void rl_sound_done( void )`
122
123Stops all sounds and releases all memory used by the sound system.
124
125* `rl_sound_t* rl_sound_create( const void* data, size_t size, int stereo )`
126
127Creates a sound from the given data. The data is just `size / 2` signed 16-bit PCM data. If `stereo` is `true`, the sound is stereo and data is [interleaved](http://en.wikipedia.org/wiki/Interleave_sequence), with 16-bits for the left channel followed by 16-bits for the right channel and so forth: LRLRLR...
128
129* `rl_sound_destroy( sound )` (macro)
130
131Frees the given sound. Do **not** free a sound that's still playing.
132
133* `int rl_sound_play( const rl_sound_t* sound, int repeat, rl_soundstop_t stop_cb )`
134
135Plays a sound. If `repeat` is true, the sound will be repeated *ad infinitum* or until manually stopped. If `stop_cb` is not `NULL`, it'll be called when the sound stops, either because of calls to `rl_sound_stop` or `rl_sound_stop_all` or because it ended naturally.
136
137The returned integer is an internal voice identifier which can be used in calls to `rl_sound_stop`.
138
139* `void rl_sound_stop( int index )`
140
141Stops a sound (voice) being played.
142
143* `void rl_sound_stop_all( void )`
144
145Mutes all voices. The Ogg Vorbis music is not affected.
146
147* `int rl_sound_play_ogg( const void* data, size_t size, int repeat, rl_soundstop_t stop_cb )`
148
149Starts playing the Ogg Vorbis file contained in `data`. If `repeat` is true, the music will restart automatically. If `stop_cb` is not `NULL`, it'll be called when the music either finishes or `rl_sound_stop_ogg` is called.
150
151* `void rl_sound_stop_ogg( void )`
152
153Interrupts the Ogg Vorbis music.
154
155* `const int16_t* rl_sound_mix( void )`
156
157Mixes all the active voices and the Ogg Vorbis music, if any, and returns a pointer to the stereo, 16-bit PCM audio data buffer that can be sent directly to a properly configured audio device. The data buffer has `RL_SAMPLES_PER_FRAME` stereo samples, meaning `RL_SAMPLES_PER_FRAME * 2` samples, which equals to `RL_SAMPLES_PER_FRAME * 2 * 2` bytes.
158
159### Sprites
160
161Sprites are just images with a spatial position, a layer index for depth sorting, and a visibility flag. They are blit/unblit as a group.
162
163If you redraw the entire framebuffer every frame, you should:
164
1651. Draw the framebuffer
1661. Call `rl_sprites_blit_nobg`
1671. Present the framebuffer
168
169If your background is fixed, or if you update it instead of redrawing it completely, you should:
170
1711. Update the framebuffer
1721. Call `rl_sprites_blit`
1731. Present the framebuffer
1741. Call `rl_sprites_unblit`
175
176* `void rl_sprite_init( void )`
177
178Initializes internal data.
179
180* `rl_sprite_t* rl_sprite_create( void )`
181
182Creates a sprite. The `image` field of the sprite must be initialized before any sprites are drawn, either to a valid image or to NULL (in which case the sprite is invisible.)
183
184* `rl_sprite_destroy( sprite ) (macro)`
185
186Frees a sprite.
187
188* `void rl_sprites_translate( int x0, int y0 )`
189
190Translates all sprites.
191
192* `void rl_sprites_blit_nobg( void )`
193
194Blits all sprites without saving the background. Use this when the background is redrawn every frame.
195
196* `void rl_sprites_blit( void )`
197
198Blits all sprites saving their background. The `RL_BG_SAVE_SIZE` config macro defines the size of the scratch memory that will be used to save the sprites' backgrounds, so you may need to adjust its value if you blit too many sprites.
199
200* `void rl_sprites_unblit( void )`
201
202Unblits all sprites.
203
204### Maps
205
206TODO
207
208
209### Misc
210
211TODO (memory management, endianess conversion, userdata and compile-time configuration.)
212
213## Conversion Tools
214
215### rlrle.lua
216
217TODO
218
219### rlmap.lua
220
221TODO
222
223### rltile.lua
224
225TODO
226
227### rltileset.lua
228
229TODO
230
231## A Minimum libretro Core
232
233TODO, but see `test/libretro/test.c`.
234
235## License
236
237Released under the zlib/libpng license.
238