Raydium API Reference

CQFD Corp.

This document is the most up-to-date version. This is a work in progress:
only the core of Raydium is described here (no physics, no scripting,
old network, no particles, no profiling, no data&proc registration,
no new smooth camera functions and no parser), and there's again some
errors and wrong informations. Try, wait, or contribute ;)

Functions from ode.c, php.c, parser.c, profile.c, rayphp.c, register.php
are missing.

Index of all Raydium functions

This document is autogenerated, any change will be lost,
use RaydiumApiReferenceComments for any need.
Generated: 2005-03-10 18:25:09, for Raydium 0.610

1 Introduction to Raydium:

1.1 About:

Well, first of all, let me talk about Raydium goals: this project
aims to be simple, easy to use, portable, and quite fast.

Raydium is a C written abstract layer, on top of OpenGL,
GLU and GLUT: this means you can write an entire 3D
application without calling any OpenGL function.
Want to draw an object ? call the suitable Raydium function,
and all textures and vertices will be loaded, and your object drawn.
Want to make an explosion ? Same thing: call the right function.
Note that you can call OpenGL functions anyway, if necessary.

About portability, I can say a few things: Raydium was initially
planned for linux only, but with an "clean" (nearly ANSI) code,
and, in facts, we have been able to compile Raydium under VC6 (Windows)
and mingw with a very few modifications.
So you can expect a correct result on any system providing
OpenGL (at least 1.2), GLU, GLUT and a C compiler.

As we (Corp?.) needed a library for our own games, demos,
and... and things like that, and as I was interested by OpenGL,
I starts to write Raydium.

Raydium is perfect for outdoors spaces, integrating a landscape engine,
with suitable physic, supports dynamic lighting, fog, blending, water and
waves, terraforming, and more.

This features list will probably grow up during Raydium developpement.

You'll find, in this document, a list of many functions and possibilities
of Raydium.

After this short introduction, let's talk about the API itself,
starting with the main file (from the programmer's point of vue)
of Raydium: common.c

1.2 Defines:

As mentioned above, the file common.c is quite interesting,
for several reasons: first, as this file includes all others Raydium's
files, you can have an overview of the whole project, just by looking at this.

It can also be used as a "quick help", since all variables are declared
here, and not in the corresponding files. I mean, for example,
that "raydium_light_intensity..." will be declared in common.c,
not in light.c . There's many reasons for using such "style",
but you must only retain that it is simpler for you :)

Ok, after this little disclaimer, we can have a look to the first part
of our file.

After usual #include (nothing interesting here), we find some #defines.

generic limits

The first #define block determine limits of your application,
and here you are the actual values for basic defines:

#define RAYDIUM_MAX_VERTICES 500000
#define RAYDIUM_MAX_TEXTURES 256
#define RAYDIUM_MAX_LIGHTS 8
#define RAYDIUM_MAX_NAME_LEN 255
#define RAYDIUM_MAX_OBJECTS 1024

- As you may expect, MAX_VERTICES defines the amount of memory you'll
waste with vertex tables. These tables will contain all loaded objects,
then remember each time you draw something (object),
Raydium loads it (if not already done). Currently, there is no "delete"
mechanism implemented (except by deleting all objects).
Let me give you a scale: with an Athlon XP1900+, GeForce 3,
actual Raydium devel. version 0.31, with around 100 000 vertices,
losts of options (sky, blending, 2 lights, 15 textures, ...),
Raydium renders ~ 45 FPS. Beyond this, a very correct object uses less
than 10 000 vertices. So 500 000 vertices, the actual default,
is quite large. It's also important to talk about memory: Linux is
very efficient on this point, and allocates only "really used" memory.
Under Linux, with the above scene, Raydium used about 20 MB (data only),
instead of "much more" (~ 5x). I haven't made any test about this under
Windows, but we can expect worse results.

- There's nothing really important to say about MAX_TEXTURES,
since that doesn't influence the amount of memory used. You are not
limited to 8 bits values, but 256 seems very comfortable (and you must
pay attention to the capacities of your 3D hardware !)

- The next define, MAX_LIGHTS is very important: OpenGL, for now
(version 1.3 and lower), impose 8 lights at least, and all current
hardware doesn't manage more. If this situation is likely to evolve,
we will move this #define to a variable, and will ask hardware for its
capacities at initialization, but, for the moment, do not exceed 8.

- Next, NAME_LEN, limits the maximum length of strings (textures and
objects names) used by Raydium. Default value should be perfect.
(avoid higher values, since it could slow down name searches)

- MAX_OBJECTS use the same mechanism as MAX_TEXTURES, and addition
with the fact that hardware is not concerned, it can be ignored.

Options and parameters

This is the next part of our #define section, I will not explain these
constants here, but in respective sections, so you'll have just you to
remember they're declared here.

1.3 Basic vars:

This section aims to describe each variable Raydium use, one by one.
Some (most ?) of them are used internaly only, but you could need to access
it. Moreover, you'll better understand how Raydium works by looking at
these variables.

Keyboard input

Following variables can be found:

raydium_key_last will always contains the last key (normal or special)
pressed down. You'll find a explanation about normal and special keys above.

raydium_key[] hosts all special keys state. Currently, you must use
GLUT define's (Raydium aliases will come soon), limited to
following keys:

- GLUT_KEY_F1 to GLUT_KEY_F12
- GLUT_KEY_LEFT, GLUT_KEY_RIGHT, GLUT_KEY_UP, GLUT_KEY_DOWN
- GLUT_KEY_PAGE_UP, GLUT_KEY_PAGE_DOWN
- GLUT_KEY_HOME, GLUT_KEY_END, GLUT_KEY_INSERT

These are "special" keys: they have 2 states. released (0),
and pressed (non zero). It means you can do something
(move an object, turn on a light) UNTIL user stops to press the key.
"Normal" keys have a different behavior: you can do something IF user
press a key (exit from application if ESC is pressed, for example).
You'll have no information about key's release.

A normal key is sent through raydium_key_last, a special one through
raydium_key[] AND raydium_key_last.

You must see raydium_key_last as an "event", fired when the user press
a key (ANY key: special or not). When a normal key is pressed, you'll get
the ASCII value + 1000 assigned to raydium_key_last. (1027 for "ESC", for
example)

Here is a method to use special keys:

if(raydium_key[GLUT_KEY_UP]) move_car();

Yes, it's easy. You can also use

if(raydium_key_last""==""GLUT_KEY_UP) explose();

for example, if you need to carry out a specific action.

It's ok for you ? use raydium_key[] to keep the car moving until
user release UP key, or use raydium_key_last to explode the car
when the user tries to start it :)

Mouse input

Easy.

You can get actual mouse position on the window (relative to window's
position on screen, I mean) with raydium_mouse_x and raydium_mouse_y
(GLuint), starting at (0,0) for upper left
(Warning: some GLUT implementations can give mouse position even
when mouse is out of the window ! Check boundaries before using these values).

Raydium use: 1 for left button, 2 for right button, and 3 for
middle button (0 for none) with raydium_mouse_clic for the last clic
value. (generated one time per clic)

You can permanently get a button's state, up (0) or down (non zero),
using raydium_mouse_button[x], where x is 0 for left button, 1 for right
one, and 2 for middle button.

Textures

raydium_texture_index and raydium_texture_current (GLuint) are used
internaly to determine repectively how many textures are loaded,
wich is the current one.

The next variable, raydium_texture_filter, is very important. You can
assign RAYDIUM_TEXTURE_FILTER_NONE (default), RAYDIUM_TEXTURE_FILTER_BILINEAR
or RAYDIUM_TEXTURE_FILTER_TRILINEAR (recommended).

Using no texture filter can gives you higher framerate on old 3D hardware,
but this is quite ugly.

You can activate bilinear filtering without any framerate impact on
most recent video cards, and get a much more attractive rendering.

Trilinear filtering uses Bilinear filtering and MipMaps. A MipMaped?
texture is a duplicated texture (3 times, with Raydium), but at different
sizes. A 512x512 texture will generate, for example, a (smoothed)
256x256 texture, and a (smoothed) 128x128 one. Your video card will
use these textures according to distance from POV (point of vue),
reducing flickering effect.

This is the best filtering Raydium can use, for a great rendering quality.
Good and recent 3D hardware can do trilinear filtering in a single pass,
so it must be the default setting for your application.

About raydium_texture_filter itself: changing this variable will not modify
the rendering, but the way to load textures. It means you can (for example)
use trilinear only for landscape textures, and bilinear for others.
It also means you must reload (erase) a texture to change it's filter.

Note that Raydium will never use trilinear filter with blended (transparent)
textures, for good reasons :)

Let's talk quickly about next (internal) texture variables:
raydium_texture_blended[] is a flag table, where each element is
non zero for a blended (RGBA) texture, and 0 for an RGB one.

For Raydium, when a texture does not contain a "bitmap" (texture file,
for example), it contains a plain color, and this color is stored in
raydium_texture_rgb[][4] (4 is for RGBA, values between 0 and 1).
You can load an rgb texture with "rgb" keyword. For example, instead of
loading "red.tga", you can load "rgb(0.8,0.1,0.1)".

raydium_texture_name[] table simply contains texture filenames.

Last thing, raydium_texture_to_replace,
can be used to erase an already loaded texture.
Set the variable to n, and load a new texture: texture number "n" will be
replaced in memory.

Projection

Raydium supports 2 types of projection: RAYDIUM_PROJECTION_ORTHO
(orthographic) and RAYDIUM_PROJECTION_PERSPECTIVE.

First of all, let us point out what "projection" is. Using a "perspective"
projection, closest objects will looks larger than the orthers. It is
typically used in video games (since human eye runs like that),
by opposition to orthographic projection, wich is mostly used by 3D
modeling tools. The principle is simple, discover it by yourself :)

Raydium reads raydium_projection to determine wich method to use.
Each projection is configured with raydium_projection_* variables.
Some of these variables are used both by "perspective" and "orthographic"
projections.

Here is what common.c says:

GLFLOAT RAYDIUM_PROJECTION_FOV; // PERSPECTIVE ONLY
GLFLOAT RAYDIUM_PROJECTION_NEAR; // PERSPECTIVE & ORTHO
GLFLOAT RAYDIUM_PROJECTION_FAR; // PERSPECTIVE & ORTHO
GLFLOAT RAYDIUM_PROJECTION_LEFT; // ORTHO ONLY
GLFLOAT RAYDIUM_PROJECTION_RIGHT; // ORTHO ONLY
GLFLOAT RAYDIUM_PROJECTION_BOTTOM; // ORTHO ONLY
GLFLOAT RAYDIUM_PROJECTION_TOP; // ORTHO ONLY

You've probably noticed that orthographic projection defines a "box"
with your screen: near, far, left, right, bottom. Everything out ouf
this box will never be displayed.

Perspective projection is based on FOV: Field Of Vision, given in degrees.
A common "human" fov is 60°, up to 90° without any noticeable deformation.
"near" and "far" are used for many things: Z-Buffer precision is affected,
and clipping too: as with "orthographic", nothing will be displayed beyond
"far", and fog, if enabled, will hide this "limit". This is right for "near",
too, but without fog, obviously :)

Also remember that decreasing FOV will zoom in.

You must call raydium_window_view_update() after any modification on one
(or more) of these variables (see "Window Managment" section for more
information)

Frame size and color

raydium_window_tx and raydium_window_ty are read-only variables,
providing you actual frame size.

raydium_background_color[4] is a RGBA table, and will be used for
frame clearing, and fog color. You can change this variable, and call
respective update functions (frame and fog), or simply use
raydium_background_color_change(GLfloat r, GLfloat g, GLfloat b, GLfloat a).

More informations in corresponding sections.

Vertices

Vertices data structure is distributed in 4 parts:

- raydium_vertex_* : these tables will simply contains vertices coordinates

- raydium_vertex_normal_* : vertices normals. Raydium will maintain
two distinct normal tables, and this one will be used for calculations.

- raydium_vertex_normal_visu_* : the other normal table, used for
lighting. Smoothing "visu" normals will provides a better rendering, and Raydium includes
all necessary functions to automate this task.

- raydium_vertex_texture_u, *raydium_vertex_texture_v,
*raydium_vertex_texture contains, for each vertex stored
in the vertices data structure, u and v mapping information,
and associated texture number. U and V are texture mapping coordinates.

Raydium can automatically generates some of these data
(normals and uv coords, that is), Read "Vertices" section above
for more information.

PLEASE, do not write directly in these tables, use dedicated functions.

Objects

Objects are loaded in Vertices stream, identified by a "start" and an "end"
(raydium_object_start[] and raydium_object_end[]) in this stream.
An index is incremented each time you load an object
(GLuint raydium_object_index). Filename is also stored in
raydium_object_name[][]. Go to "Objects" section to know more.

Lights

First of all, raydium_light_enabled_tag contains 0 when light is
disabled, non-zero otherwise. This is a read-only variable, so use
suitable functions.

Currently, for Raydium, a light can have 3 states: on, off, or blinking.
raydium_light_internal_state[] stores this.

Next comes all light's features: position, color, intensity. You can
modify directly these variables, and call update fonctions,
if needed (not recommended).

Next, raydium_light_blink_* are used internaly for blinking lights,
setting lowest, higher light intensity, and blinking speed.
Do noy modify these variables, use suitable functions.

You should read the chapter dedicated to lights for more information.

Fog

Only one variable, here: raydium_fog_enabled_tag, switching from zero
to non zero if fog is enabled. Do NOT use this variable to enable or
disable fog, but suitable functions, this variable is just a tag.

Camera

Since many calls to camera functions are done during one frame,
Raydium must track if any call to these functions was already done,
using raydium_frame_first_camera_pass boolean.

raydium_camera_pushed, also used as a boolean, stores stack state.
When you place your camera in the scene with Raydium, it pushes matrix
on top of the stack, so you can modify it (the matrix), placing an object
for example, an restore it quickly after, by popping matrix off.

2 Maths:

2.1 Little introduction to trigo.c:

This section is mostly designed for internal uses, but provides some
usefull maths functions.

2.2 GLfloat raydium_trigo_cos (GLfloat i):

Obvious (degrees)

2.3 GLfloat raydium_trigo_sin (GLfloat i):

Obvious (degrees)

2.4 GLfloat raydium_trigo_cos_inv (GLfloat i):

Obvious (degrees)

2.5 GLfloat raydium_trigo_sin_inv (GLfloat i):

Obvious (degrees)

2.6 raydium_trigo_abs(a) (macro):

Obvious

2.7 raydium_trigo_min(a,b) (macro):

Obvious

2.8 raydium_trigo_max(a,b) (macro):

Obvious

2.9 raydium_trigo_isfloat(a) (macro):

Test two cases : "Not a Number" and "Infinite"

2.10 void raydium_trigo_rotate (GLfloat * p, GLfloat rx, GLfloat ry, GLfloat rz, GLfloat * res):

Rotate p (GLfloat * 3) by (rx,ry,rx) angles (degrees).
Result is stored in res (GLfloat * 3)

2.11 void raydium_trigo_pos_to_matrix (GLfloat * pos, GLfloat * m):

Generates a ODE style matrix (16 Glfloat) from pos (GLfloat * 3)

2.12 void raydium_trigo_pos_get_modelview (GLfloat * res):

Stores the current OpenGL MODELVIEW matrix in res (16 GLfloat)

3 Logging:

3.1 Introduction to log.c:

Raydium uses and provides his own logging system,
hidden behind a single function, as shown below.

3.2 void raydium_log (char *format, ...):

This function must be used like "printf", using a format
("%s, %i, %x, ...") and then, suitable variables,
but without the end-line char ('\n')

raydium_log("You are player %i, %s",player_number,player_name);

For now, this function writes to the parent terminal and the in-game console, with "Raydium: " string prefix.
The user can force logging to a file, using --logfile command line switch.

4 Random:

4.1 Introduction:

These functions deals with random numbers generation.

4.2 void raydium_random_randomize (void):

This function initialize the random number generator
with current time for seed.
Note: You are not supposed to use this function.

4.3 GLfloat raydium_random_pos_1 (void):

"positive, to one": 0 <= res <= 1

4.4 GLfloat raydium_random_neg_pos_1 (void):

"negative and positive, one as absolute limit": -1 <= res <= 1

4.5 GLfloat raydium_random_0_x (GLfloat i):

"zero to x": 0 <= res <= x

4.6 GLfloat raydium_random_f (GLfloat min, GLfloat max):

min <= res <= max (float)

4.7 int raydium_random_i (int min, int max):

min <= res <= max (integer)

4.8 char raydium_random_proba (GLfloat proba):

Returns true or false (0 or 1) depending of "proba" factor.
proba must be: 0 <= proba <=1
ex: 50% = 0.5

5 Fog:

5.1 Introduction:

Fog is usefull for two major reasons:

1. Realism: Just try, and you'll understand:
amazing depth impression, no ?

2. Speed: For a correct fog effect (i'm talking
about estetic aspect), you must bring near_clipping to a closer value,
reducing the overall number of triangles displayed at the same time.

5.2 void raydium_fog_enable (void):

Obvious

5.3 void raydium_fog_disable (void):

Obvious

5.4 void raydium_fog_color_update (void):

If you have modified raydium_background_color array, you must
call this function, applying the specified color to hardware.
See also: raydium_background_color_change

5.5 void raydium_fog_mode (void):

Do not use. Instable prototype.

6 Window management:

6.1 Introduction:

Some important functions, used for window creation and managment.

6.2 void raydium_window_close (void):

This function is called by Raydium, do not use.

6.3 void raydium_window_create (GLuint tx, GLuint ty, char rendering, char *name):

You must call this function once in your program, with following arguments:

1. tx, ty: window size, in pixel
2. rendering: window mode: RAYDIUM_RENDERING_* (NONE, WINDOW, FULLSCREEN)
3. name: window's name

Raydium is using GLUT for window management, and GLUT fullscreen is not
the same between various implementations, and can fail,
so use a standard window size (640x480, 800x600, ...) for fullscreen mode.

Note that user can force fullscreen using --fullscreen on the command line.

6.4 void raydium_window_resize_callback (GLsizei Width, GLsizei Height):

This function is automaticaly called during a window resize,
and resize OpenGL rendering space.

There is almost no reason to call this function by yourself.

6.5 void raydium_window_view_update (void):

If you've changed 3D window size (clipping: raydium_projection_*),
apply to hardware with this fonction.

6.6 void raydium_window_view_perspective(GLfloat fov, GLfloat near, GLfloat far):

All-in-one function: sets all "perspective" variables, and updates.

7 Capture (2D):

7.1 Quickview:

Captures are made in TGA format (without RLE compression) and saved into
the current directory.
This function may fail (garbage in resulting capture) if frame size if
not "standard", mostly after a window resize.

7.2 void raydium_capture_frame(char *filename):

Capture current frame to filename.

7.3 void raydium_capture_frame_auto(void):

Same as above, but to an auto-generated filename (raycap*).

8 Background:

8.1 void raydium_background_color_change (GLfloat r, GLfloat g, GLfloat b, GLfloat a):

Will change raydium_background_color array and apply this modification.
(will update fog color, obviously).

9 Frame clearing:

9.1 void raydium_clear_frame (void):

You need to call this function every frame to clear all hardware buffers.

9.2 void raydium_clear_color_update (void):

Will apply background color modification. Probably useless for you.

10 Lights:

10.1 Introduction to Raydium light system:

When we starts Raydium development, the main idea was to use native OpenGL
lights, and not lightmaps or another method.

This method (native lights) provides 8 simultaneous movable lights,
and is quite effective with recent OpenGL hardware.

You can modify intensity, position, color, you can turn on any light at
any time, make them blinking... Mixing all theses features can result
many effects, as realtime sunset, flashing lights for cars, explosions, ...

Usage is very easy: no need to create lights, just turn them on.

See also: LightMaps

10.2 void raydium_light_enable (void):

Obvious.

10.3 void raydium_light_disable (void):

Obvious.

10.4 GLuint raydium_light_to_GL_light (GLuint l):

Probably useless for end user. (internal uses)

10.5 void raydium_light_on (GLuint l):

Turns l light on ( 0 <= l <= RAYDIUM_MAX_LIGHTS )

10.6 void raydium_light_off (GLuint l):

Turns l light off

10.7 void raydium_light_switch (GLuint l):

Will swith l light state (from "on" to "off", for example).

10.8 void raydium_light_update_position (GLuint l):

Updates raydium_light_position[l] array changes to hardware.
This function is now used internaly by Raydium,
so you have no reasons to call it by yourself.

10.9 void raydium_light_update_position_all (void):

See above.

10.10 void raydium_light_update_intensity (GLuint l):

See above.

10.11 void raydium_light_update_all (GLuint l):

See above.

10.12 void raydium_light_move (GLuint l, GLfloat * vect):

Moves light to position vect for light l (vect is GLfloat[4]: x,y,z,dummy).

Just move your lights before camera placement, or your changes
will be applied to the next frame only.

10.13 void raydium_light_reset (GLuint l):

This function will restore all defaults for l light.

10.14 void raydium_light_blink_internal_update (GLuint l):

Useless for end-user.

10.15 void raydium_light_blink_start (GLuint l, int fpc):

Makes l light blinking at fpc (frames per cycle) rate.
This function will use timecalls soon ("fpc" -> "hertz")

10.16 void raydium_light_callback (void):

Useless for end-user.

11 Keyboard & keys:

11.1 void raydium_key_normal_callback (GLuint key, int x, int y):

Internal callback.

11.2 void raydium_key_special_callback (GLuint key, int x, int y):

Internal callback.

11.3 void raydium_key_special_up_callback (GLuint key, int x, int y):

Internal callback.

11.4 int raydium_key_pressed (GLuint key):

Will return state of key in the raydium_keys[] array.
This function is usefull to test keyboard from PHP, since RayPHP doest not
support array for now.

12 Mouse:

12.1 Introduction:

Mouse API is almost explainded at the top of this guide, but here it
is some other usefull functions (macros, in facts)

12.2 raydium_mouse_hide() (macro):

Hides mouse cursor.

12.3 raydium_mouse_show() (macro):

Shows mouse cursor.

12.4 raydium_mouse_move(x,y) (macro):

Moves cursor to (x,y) position (in pixel).
Example if you want to move cursor at window's center:

raydium_mouse_move(raydium_window_tx/2, raydium_window_ty/2);

12.5 void raydium_mouse_init (void):

Internal use.

12.6 void raydium_mouse_clic_callback (int but, int state, int x, int y):

Internal callback.

12.7 void raydium_mouse_move_callback (int x, int y):

Internal callback.

12.8 int raydium_mouse_button_pressed (int button):

returns button state. (See first part of this document)

13 Textures:

13.1 Introduction:

For now, Raydium only handles TGA uncompressed texture.
As explainded in the first part of this guide, Raydium provides three
texture filters (none, bilinear, trilinear using MipMaps ).

Texture sizes must be a power of two, 8 (alpha mask), 24 (RGB) or 32 (RGBA) bits.

Raydium now supports materials with a simple "rgb(r,g,b)" string
as texture name, where r, g and b are 0 <= x <= 1 (floats).
Texture clamping and multitexturing are supported by Raydium, but not
documented here for now. If you're interested, have a look to source code, or
take a look to the Wiki.

Tips: "BOX_", ";", "|".

13.2 char raydium_texture_size_is_correct (GLuint size):

Returns true if size is a correct texture size, depending of
hardware capacities and "power of 2" constraint.

13.3 GLuint raydium_texture_load_internal (char filename, char as):

Internal use.

13.4 GLuint raydium_texture_load (char *filename):

Loads "filename" texture into hardware memory. Function results
texture index, but in most cases, you can identify later a texture
by his name, without providing his index, so you can probably ignore
this value.

0 is returned if texture loading have failed.

13.5 GLuint raydium_texture_load_erase (char *filename, GLuint to_replace):

Same as above, but to_replace texture (index) is erased with filename.

13.6 char raydium_texture_current_set (GLuint current):

Switch active texture to "current" index. Mostly used for runtime object
creation:
"set current texture, add vertices, set another texture,
add vertices, ... and save all to an objet"
(see below for vertices management).

13.7 char raydium_texture_current_set_name (char *name):

Same as above, but using texture name. This function will load name
if not alread done.

13.8 GLuint raydium_texture_find_by_name (char *name):

Returns index for texture "name", and load it if not already done.

13.9 void raydium_texture_filter_change (GLuint filter):

This function will change all filters at anytime.
Please note that this function will reload all textures and can be very slow.

// will switch all textures to bilinear filter.
raydium_texture_filter_change(RAYDIUM_TEXTURE_FILTER_BILINEAR)

14 Rendering:

14.1 int raydium_rendering_prepare_texture_unit (GLenum tu, GLuint tex):

This function will "prepare" hardawre texture unit tu to render tex texture.
There almost no reason to call this function by yourself.

14.2 void raydium_rendering_internal_prepare_texture_render (GLuint tex):

Same as above, but for texture unit #0 only.

14.3 void raydium_rendering_internal_restore_render_state (void):

Internal. Deprecated.

14.4 void raydium_rendering_from_to (GLuint from, GLuint to):

Renders vertices from from to to.
Using object management functions is a better idea.

14.5 void raydium_rendering (void):

Renders all vertices (probably useless, now).

14.6 void raydium_rendering_finish (void):

You must call this function at the end of each frame. This will flush all
commands to hardware, fire a lot off callbacks, and prepare next frame.

14.7 void raydium_rendering_wireframe (void):

Switch to wireframe rendering.

14.8 void raydium_rendering_normal (void):

Switch back to standard rendering.

14.9 void raydium_rendering_rgb_force (GLfloat r, GLfloat g, GLfloat b):

Force all RGB colored vertices to take (r,g,b) color. One example of this
use is for making "team colored" cars : Do not apply textures to some faces
while modelling, and force to team color each time you render a car.

14.10 void raydium_rendering_rgb_normal (void):

Disable "rgb force" state. See above.

14.11 void raydium_rendering_displaylists_disable(void):

Disable display lists usage.
Some old video cards and broken drivers may get better performances WITHOUT
display lists (on large objects, mainly).

14.12 void raydium_rendering_displaylists_enable(void):

Enable display lists usage. default state.

15 Particle engine:

15.1 Introduction:

This is the second version of Raydium's particle engine. This engine is build
on top of a dedicated file format (.prt and .sprt files), describing most
(up to all, in facts) properties of generators.
It probably better to start by an example (fountain.prt) :

// Simple blue fountain (change 'vector' if needed)
ttl_generator=5;
ttl_particles=1.5;
ttl_particles_random=0;
 
particles_per_second=200;
 
texture="flare_nb.tga";
 
size=0.1;
size_inc_per_sec=0.1;
 
gravity={0,0,-5};
vector={0,0,4};
vector_random={0.2,0.2,0.2};
 
// RGBA
color_start={0.6,0.6,1,0.5};
color_start_random={0,0,0.2,0};
color_end={1,1,1,0.1};
 
// end of file.

.prt files are readed using parsing functions (see appropriate chapter, if
needed), and the list of all available properties can be found in particle2.c
source file. A full toturial is also available on Raydium's Wiki.

Once the particle file is written, you only need to load the file using the
suitable function (see below). Some anchor are available to link generators to
physic entities, if needed, as callbacks for a few events (one, for now).

.sprt files are used to create a "snapshot" of particles, used for example by
3D captures, and are not meant to be edited by hand.

15.2 void raydium_particle_name_auto (char prefix, char dest):

Will generate a unique string using prefix. The string is created using
space provided by dest.
You can use this function when building a new generator.

15.3 void raydium_particle_init (void):

Internal use.

15.4 char raydium_particle_generator_isvalid (int g):

Internal use, but you can call this function if you want to verify if a
generator's id is valid (in bounds, and loaded).

15.5 int raydium_particle_generator_find (char *name):

Lookups a generator using is name. Returns -1 if name is not found.

15.6 int raydium_particle_find_free (void):

Finds a free particle slot.

15.7 void raydium_particle_generator_delete (int gen):

Deletes a generator.

15.8 void raydium_particle_generator_delete_name (char *gen):

Same as above, but using generator's name.

15.9 void raydium_particle_generator_enable (int gen, char enabled):

Activate a disabled generator (see below).

15.10 void raydium_particle_generator_enable_name (char *gen, char enable):

Disable a generator (TTL is still decremented).

15.11 void raydium_particle_preload (char *filename):

Loads .prt file and associated textures into suitable caches.
Call this function if you want to avoid (small) jerks caused by "live"
loading a generator.

15.12 void raydium_particle_generator_load_internal (int generator, FILE * fp, char *filename):

Internal use.

15.13 int raydium_particle_generator_load (char filename, char name):

Loads generator from filename as name. This name will be used for
future references to this generator, as the returned interger id.

15.14 void raydium_particle_generator_update (int g, GLfloat step):

Internal use.

15.15 void raydium_particle_update (int part, GLfloat step):

Internal use.

15.16 void raydium_particle_callback (void):

Internal use.

15.17 int raydium_particle_state_dump(char *filename):

Dumped current particles to filename (.sprt [static particles]).

15.18 int raydium_particle_state_restore(char *filename):

Append .sprt filename to current scene.

15.19 void raydium_particle_draw (raydium_particle_Particle * p, GLfloat ux, GLfloat uy, GLfloat uz, GLfloat rx, GLfloat ry, GLfloat rz):

Internal use.

15.20 void raydium_particle_draw_all (void):

Internal use.

15.21 void raydium_particle_generator_move (int gen, GLfloat * pos):

Moves gen generator to pos position (3 * GLfloat array).

15.22 void raydium_particle_generator_move_name (char gen, GLfloat pos):

Same as above, but using generator's name.

15.23 void raydium_particle_generator_move_name_3f (char *gen, GLfloat x, GLfloat y, GLfloat z):

Same as above, using 3 different GLfloat values.

15.24 void raydium_particle_generator_particles_OnDelete (int gen, void *OnDelete?):

Sets a callback for gen, fired when any particle of this generator is
deleted, providing a easy way to create "cascading" generators.
The callback must respect the following prototype:

void cb(raydium_particle_Particle *)

Do not free the provided particle.

15.25 void raydium_particle_generator_particles_OnDelete_name (char gen, void OnDelete?):

Same as above, but using generator's name.

16 Callbacks:

16.1 Introduction:

This file contains many initializations, a few internal callbacks, but
will provides a very important function for end-user, wich will
gives user display function to Raydium: see below

16.2 void raydium_callback_image (void):

Internal use.

16.3 void raydium_callback_set (void):

Internal use.

16.4 void raydium_callback (void (*loop)):

This function will loop over the provided display function, indefinitely.
"loop" must be:

void loop(void)

17 Normals:

17.1 Introduction:

This file provides some usefull functions for normal generation and smoothing.
You can find some more informations about normals at the top of this guide.

17.2 void raydium_normal_generate_lastest_triangle (int default_visu):

Generate normal for the last created triangle (see raydium_vertex_index)
if default_visu is true ( != 0 ), this function will restore "visu"
normals too.

17.3 void raydium_normal_restore_all (void):

This function restore visu normals with standard ones (raydium_vertex_normal_*)

17.4 void raydium_normal_regenerate_all (void):

This function will regenerate standard and visu normals for the whole
scene (ground, objects, ...).

17.5 void raydium_normal_smooth_all (void):

This function will smooth the whole scene, using adjacent vertices.
Note this function can take a lot of time.

18 vertices:

18.1 Introduction:

You can create objets at runtime, if needed, using the following functions.
Each of theses functions adds only one vertex so, obviously, you need to
call three time the same function to add one triangle.

18.2 void raydium_vertex_add (GLfloat x, GLfloat y, GLfloat z):

Adds a vertex at (x,y,z).

18.3 void raydium_vertex_uv_add (GLfloat x, GLfloat y, GLfloat z, GLfloat u, GLfloat v):

Same as above, but providing texture mapping informations with u and v.

18.4 void raydium_vertex_uv_normals_add (GLfloat x, GLfloat y, GLfloat z, GLfloat nx, GLfloat ny, GLfloat nz, GLfloat u, GLfloat v):

Same as above, giving vertex's normal with (nx,ny,nz).

19 Land:

19.1 Introduction:

Historically, this file was quite complex, since Raydium was using
his own physic. Now, this file is almost empty, since ODE integration
now provides new landscape functions.

20 Sky and environement boxes:

20.1 Introduction:

Skyboxes are mostly automated.

For now, Raydium will use BOXfront.tga, BOXback.tga, BOXleft.tga,
BOXright.tga, BOXbottom.tga and BOXtop.tga and will draw a
skybox only if fog is disabled (this is not for technical reasons,
but only for realism, just think about it ;)... but you can force
skybox with fog using raydium_sky_force if you really want).

20.2 void raydium_sky_box_cache (void):

As skybox texture are sometimes large files, you can pre-load skybox
with this function. If you don't do it, Raydium will load textures
during the first frame of your application.

20.3 void raydium_sky_box_render (GLfloat x, GLfloat y, GLfloat z):

Internal use.

21 "Internal" informations access:

21.1 void raydium_internal_dump (void):

This function is now systematically called by Raydium at application's exit,
displaying some informations about loaded textures, objects, registered data,
network statistics.

21.2 void raydium_internal_dump_matrix (int n):

Dumps matrix to console.
n values are:

0 for GL_PROJECTION_MATRIX
1 for GL_MODELVIEW_MATRIX

22 Files:

22.1 Warning:

It's important to use only functions with raydium_file_* prefix.
All other functions may change or disappear. Upper level functions are
available (see object.c).

22.2 Introduction:

file.c use .tri mesh files (text), available in 3 versions:

1. version 1: providing normals and uv texture mapping informations.
2. version 0: providing normals.
3. version -1: only providing vertices.

Version 1 example file:

1
5.1 15.75 -3.82 0.0000 0.0000 -1.0000 0.5158 0.5489 rgb(0.5,0.5,0.5)
6.3 11.75 -3.82 0.0000 0.0000 -1.0000 0.5196 0.5365 rgb(0.5,0.5,0.5)
5.0 11.75 -3.82 0.0000 0.0000 -1.0000 0.5158 0.5365 rgb(0.5,0.5,0.5)
...

You can find the file version on first line, and then data.
Next lines: vertex position (x,y,z), normal (x,y,z), texture mapping (u,v)
and texture (string).

22.3 void raydium_file_dirname(char dest,char from):

Reliable and portable version of libc's dirname function.
This function extracts directory from from filename, and writes it
to dest.
No memory allocation will be done by the function.

22.4 void raydium_file_log_fopen_display(void):

Display (console) all filenames that were opened before the call.
--files command line option will call this function at the application's
exit, closed or not.

22.5 FILE raydium_file_fopen(char file, char *mode):

Raydium wrapper to libc's fopen function.
This function will:
- Update some stats
- Try to download the file from repositories if no local version is found, or
will try to update the file if asked (--repository-refresh or
repository-force). See R3S on Raydium's Wiki.

22.6 void dump_vertex_to (char *filename):

This function save all scene to filename (.tri file) in version 1.
Vertice may be sorted.
Please, try to do not use this function.

22.7 void dump_vertex_to_alpha (char *filename):

Now useless and deprecated.

22.8 int raydium_file_set_textures (char *name):

Internal use.
This function analyze texture filename, and search for extended multitexturing
informations (u,v and another texture).

22.9 void read_vertex_from (char *filename):

Loads filename. Again, avoid use of this function.

23 Camera:

23.1 Introduction:

Raydium provides camera management functions, allowing the coder to
move camera with very simple functions, even for complex moves.
You have to place your camera once per frame (not more, not less).

"look_at" style functions can be affected by raydium_camera_look_at_roll
global variable, if needed.

A few words about camera path: Take a look to a .cam file if you want to
understand this simple file format, but you probably only need the cam.c
application, dedicated to camera path creation.

Some camera functions are provided by physics module, see suitable chapter.

23.2 void raydium_camera_vectors (GLfloat * res3):

This function will return two vectors (2 * 3 * GLfloat), giving the camera
orientation (front vector and up vector). At this day, the up vector is
always the same as the world up vector, even if the camera is rotated
or upside down (and yes, this MUST be corrected :).

Designed for internal uses, before all.

23.3 void raydium_camera_internal (GLfloat x, GLfloat y, GLfloat z):

Internal use.

23.4 void raydium_camera_place (GLfloat x, GLfloat y, GLfloat z, GLfloat lacet, GLfloat tangage, GLfloat roulis):

Sets the camera at (x,y,z) position, and using (lacet,tangage,roulis)
as rotation angles.

23.5 void raydium_camera_look_at (GLfloat x, GLfloat y, GLfloat z, GLfloat x_to, GLfloat y_to, GLfloat z_to):

Sets the camera at (x,y,z) position, and looks at (x_to,y_to,z_to).

23.6 void raydium_camera_replace (void):

You'll need to reset camera position and orientation after each object drawing.
If this is unclear to you, read the "example" section, below.

You will need to make your own 3D transformations (GLRotate, GLTranslate,
...) to draw your objects, or you can use the following function.

23.7 void raydium_camera_replace_go (GLfloat * pos, GLfloat * R):

This function will replace the camera, as raydium_camera_replace(),
but will place "3D drawing cursor" at position pos (3 GLfloat) with
rotation R (4 GLfloat quaternion).

No eulers (rotx, roty, rotz) version of this function is provided for now..
Do you really need it ?

23.8 Example of camera use:

1. place camera
2. move "drawing cursor" to object's place
3. draw object
4. reset camera to initial place (the one given at step 1)
5. move "drawing cursor" to another object's place
6. draw another object
7. [...]

Steps 4 and 5 can be done with raydium_camera_replace_go().

23.9 void raydium_camera_smooth (GLfloat px, GLfloat py, GLfloat pz, GLfloat lx, GLfloat ly, GLfloat lz, GLfloat zoom, GLfloat roll, GLfloat step):

Smooth style clone of raydium_camera_look_at.
Roll is given by roll and not global variable raydium_camera_look_at_roll
as for regular look_at function.
zoom is the requested FOV.
Play with step to modify smoothing level of the movement. A good way to use
this function is the following usage :

raydium_camera_smooth(cam[0],cam[1],cam[2],pos[1],-pos[2],pos[0],70,0,raydium_frame_time*3);

23.10 void raydium_camera_path_init (int p):

Internal use.

23.11 void raydium_camera_path_init_all (void):

Internal use.

23.12 int raydium_camera_path_find (char *name):

Lookups path's id using filename name.
This function will not try to load a camera path if it's not found, and
will return -1.

23.13 int raydium_camera_path_load (char *filename):

Obvious : use this function to load a camera path.

23.14 void raydium_camera_path_draw (int p):

Draws p camera path, as red lines. This must be done at each frame.

23.15 void raydium_camera_path_draw_name (char *path):

Same as above, but using camera path's name.

23.16 char raydium_camera_smooth_path (char path, GLfloat step, GLfloat x, GLfloat * y, GLfloat * z, GLfloat * zoom, GLfloat * roll):

Returns the (x,y,z) point of the camera path for step step, using
provided zoom (FOV) and roll angle.
It's important to note that step is a float.

23.17 void raydium_camera_smooth_path_to_pos (char *path, GLfloat lx, GLfloat ly, GLfloat lz, GLfloat path_step, GLfloat smooth_step):

"Camera on path looking to a point"
simple raydium_camera_smooth version:
Give a path name, a "look_at" point (lx,ly,lz), a current step, and
a smooth_step time factor (see raydium_camera_smooth example above).

23.18 void raydium_camera_smooth_pos_to_path (GLfloat lx, GLfloat ly, GLfloat lz, char *path, GLfloat path_step, GLfloat smooth_step):

"Camera on point looking at a path"
Same style as previous function.

23.19 void raydium_camera_smooth_path_to_path (char path_from, GLfloat path_step_from, char path_to, GLfloat path_step_to, GLfloat smooth_step):

"Camera on a path looking at another path"
Same style as previous functions.

24 Objects:

24.1 Introduction:

With the following functions, you can easily draw and manage
mesh objects (.tri file).

24.2 GLint raydium_object_find (char *name):

Lookups an object by his name. This function will return -1 if the
object's not found, and will not try to load the .tri file.

24.3 GLint raydium_object_find_load (char *name):

Same as above (raydium_object_load), but will try to load object

24.4 void raydium_object_reset (GLuint o):

Internal use. Do not call.

24.5 int raydium_object_load (char *filename):

Load filename as a .tri file, and returns corresponding id, or
-1 in case of error.

24.6 void raydium_object_draw (GLuint o):

Draws o (index) object, using current matrixes.

24.7 void raydium_object_draw_name (char *name):

Same as above, but you only have to provide object's name (".tri file").
If this object was not already loaded, this function will do it for you.

24.8 void raydium_object_deform (GLuint obj, GLfloat ampl):

Early devel state. Useless as is.

24.9 void raydium_object_deform_name (char *name, GLfloat ampl):

Early devel state. Useless as is.

24.10 GLfloat raydium_object_find_dist_max (GLuint obj):

This function will return will return the distance form (0,0,0)
to the farest point of obj object.

24.11 void raydium_object_find_axes_max (GLuint obj, GLfloat * tx, GLfloat * ty, GLfloat * tz):

This function returns the (maximum) size of the bounding box
of obj (relative to (0,0,0)).

25 Initialization:

25.1 Introduction:

This file is mainly designed for internal uses, but there's anyway
some interesting functions.

25.2 int raydium_init_cli_option (char option, char value):

This function will search command line option.
If this option is found, the functions stores any argument to value and
returns 1.
The function will return 0 if option is not found.

Example (search for: --ground)

char ground[RAYDIUM_MAX_NAME_LEN];
if(raydium_init_cli_option("ground",model))
{
setground(model);
}

25.3 int raydium_init_cli_option_default (char option, char value, char *default_value):

Same as above, but allows you to provide a default value (default) if
the option is not found on command line.

25.4 void raydium_init_lights (void):

Internal use. Must be moved to light.c.

25.5 void raydium_init_objects (void):

Internal use. Must be moved to object.c.

25.6 void raydium_init_key (void):

Internal use. Must be moved to key.c.

25.7 void raydium_init_reset (void):

This function is supposed to reset the whole Raydium engine:
textures, vertices, lights, objects, ...
Never tested yet, and probaly fails for many reasons when called more than
one time.

25.8 void raydium_init_engine (void):

Internal use. Never call this function by yourself, it may cause
huge memory leaks.

25.9 void raydium_init_args (int argc, char * *argv):

You must use this function, wich send application arguments to Raydium
and external libs (GLUT, OpenAL, ...).
This must be done before any other call to Raydium.
Example:

int main(int argc, char **argv)
{
raydium_init_args(argc,argv);
[...]

26 Signals:

26.1 Quickview:

There almost nothing to said about signals management, except that Raydium
will try to catch SIGINT signal (sended by CTRL+C sequence, for example).
There's nothing else for now, but we plan a user callback for this signal.

27 Sound and music:

27.1 Introduction:

The Raydium sound API is pretty easy to use and there's only need to use a
few functions to make your program ouput sounds or music.

On top of this, there are a bunch of functions to modify the sound behavior.

Raydium uses OpenAL and OggVorbis?? for its sounds and musics, for a basic
use of our sound API you only need to know one thing: OpenAL uses buffers
for its sounds and you need to be able to address the sounds separately.
For this we use ALuint in our code. Each buffer is associated to a source,
we have an array of all available sources and then, you only need to have
a simple int that acts as an index in this array.

This document is not an alternative to OpenAL papers, and only provides
informations about Raydium's interface to OpenAL.
See specifications here: http://www.openal.org/documentation.html

27.2 void raydium_sound_verify (char *caller):

This functions checks if any error occured during last OpenAL operation.
You don't have to call this function by yourself, since every function of
this API will do it.

27.3 int raydium_sound_Array3IsValid(ALfloat *a):

Since OpenAL is very sensitive to malformed values, this function is used
internally to check consistency of provided ALfloat arrays.

27.4 void raydium_sound_InitSource (int src):

Internal use.

27.5 int raydium_sound_LoadWav (const char *fname):

This function tries to load the fname wav file into a buffer, if
successful, it returns the source id, else 0.

27.6 int raydium_sound_SourceVerify (int src):

Internal id checks.

27.7 int raydium_sound_SetSourceLoop (int src, char loop):

Modifies the loop property of the src source (loops if loop is non-zero,
default value for a source is "true").
Returns 0 if ok, -1 if error.

27.8 int raydium_sound_GetSourcePitch (int src, ALfloat * p):

Returns current pitch for src source.

27.9 int raydium_sound_SetSourcePitch (int src, ALfloat p):

Sets pitch for src source.

27.10 int raydium_sound_GetSourceGain (int src, ALfloat * g):

Returns current gain ("volume") for src source.

27.11 int raydium_sound_SetSourceGain (int src, ALfloat g):

Sets gain ("volume") for src source.

27.12 int raydium_sound_SetSourcePos (int src, ALfloat Pos[]):

Sets 3D position of src source.
Pos is a 3 * ALfloat array.

27.13 int raydium_sound_SetSourcePosCamera(int src):

Sets 3D position of src source on the current camera position.

27.14 int raydium_sound_GetSourcePos (int src, ALfloat * Pos[]):

Returns current 3D position of src source.
Pos is a 3 * ALfloat array.

27.15 int raydium_sound_SetSourceDir (int src, ALfloat Dir[]):

Sets 3D direction of src source.
Dir is a 3 * ALfloat array.

27.16 int raydium_sound_GetSourceDir (int src, ALfloat * Dir[]):

Returns current 3D direction of src source.
Dir is a 3 * ALfloat array.

27.17 int raydium_sound_SetSourceVel (int src, ALfloat Vel[]):

Sets 3D velocity of src source.
Vel is a 3 * ALfloat array.

27.18 int raydium_sound_GetSourceVel (int src, ALfloat * Vel[]):

Returns current 3D velocity of src source.
Vel is a 3 * ALfloat array.

27.19 void raydium_sound_SetListenerPos (ALfloat Pos[]):

Sets 3D position of listener.
This is done automatically by Raydium, each frame, using camera informations
Pos is a 3 * ALfloat array.

27.20 void raydium_sound_GetListenerPos (ALfloat * Pos[]):

Returns current 3D position of listener.
Pos is a 3 * ALfloat array.

27.21 void raydium_sound_SetListenerOr (ALfloat Or[]):

Sets 3D orientation of listener.
This is done automatically by Raydium, each frame, using camera informations
Or is a 3 * ALfloat array.

27.22 void raydium_sound_GetListenerOr (ALfloat * Or[]):

Returns current 3D orientation of listener.
Or is a 3 * ALfloat array.

27.23 void raydium_sound_SetListenerVel (ALfloat Vel[]):

Sets 3D velocity of Listener.
Vel is a 3 * ALfloat array.

27.24 void raydium_sound_GetListenerVel (ALfloat * Vel[]):

Returns current 3D velocity of Listener.
Vel is a 3 * ALfloat array.

27.25 void raydium_sound_init (void):

Internal use.

27.26 int raydium_sound_SourcePlay (int src):

Plays the src source.
If src was already in "play" state, the buffer is rewinded.
Returns 0 if ok, -1 if error.

27.27 int raydium_sound_SourceStop (int src):

Stops the src source.
Returns 0 if ok, -1 if error.

27.28 int raydium_sound_SourcePause (int src):

Will pause the src source.
Returns 0 if ok, -1 if error.

27.29 int raydium_sound_SourceUnpause (int src):

src will restart playback after being paused.
Returns 0 if ok, -1 if error.

27.30 void raydium_sound_close (void):

Internal use.

27.31 int raydium_sound_load_music (char *fname):

Opens fname ogg music file and prepairs Raydium for playing it.
The music will be automatically played after a call to this function.
This function will use R3S (data repositories) if needed.
Returns 0 if ok, -1 if error

27.32 void raydium_sound_music_callback (void):

Internal use.

27.33 void raydium_sound_callback (void):

Internal use.

27.34 Example:

int sound;
sound=raydium_sound_LoadWav("explo.wav");
raydium_sound_SetSourceLoop(sound,0);
[...]
if(explosion) raydium_sound_SourcePlay(sound);

28 Timecalls:

28.1 Concept:

As you may already know, in a real time application (as a game), you need
to control in-game time evolution.
For example, you cannot increment a car position by 1 at each frame since
it will generate an irregular scrolling (a frame is never rendered within
the same time as the previous or the next one).

Raydium supports timecalls, wich are a great solution for this problem.
Usage is very simple: write a simple function, and ask Raydium to call it
at the desired rate.

28.2 Constraints:

There is an important risk with timecalls: infinite loops.
If a callback is long, it may take more CPU time than he would, as in this
very simple example:

foo() is a function, taking 200 ms for his own execution. If you ask for
a 6 Hz execution, Raydium will execute foo() six times on the first frame,
taking 1200 ms. On the next frame, Raydium will need to execute foo() 7
times (the asked 6 times, and one more for the 200 ms lost during the last
frame), taking 1400 ms, so 8 times will be needed for the next frame, then 9, ...

So you need to create callbacks as short as possible, since long callbacks
may cause a game freeze on slower machines than yours. (1 FPS syndrom)

28.3 Hardware devices and methods:

Raydium must use a very accurate system timer, and will try many methods:
/dev/rtc , gettimeofday() (Linux only) and
QueryPerformanceCounter? for win32.

gettimeofday() will use a CPU counter and is extremely accurate.
It's far the best method. (0.001 ms accuracy is possible)

/dev/rtc is quite good, and Raydium will try to configure RTC at
RAYDIUM_TIMECALL_FREQ_PREFERED rate (8192 Hz by default), but may
require a "/proc/sys/dev/rtc/max-user-freq" modification:
echo 8192 > /proc/sys/dev/rtc/max-user-freq

You may want to look at common.c for interesting defines about timecalls.

28.4 void raydium_timecall_raydium (GLfloat step):

Internal Raydium callback.

28.5 float raydium_timecall_internal_w32_detect_modulo(int div):

Internal, WIN32 only: Returns timer resolution for div divisor.

28.6 int raydium_timecall_internal_w32_divmodulo_find(void):

Internal, WIN32 only: Detects the best timer divisor for the current CPU.

28.7 unsigned long raydium_timecall_devrtc_clock (void):

Internal, Linux only: Reads and return RTC clock.

28.8 unsigned long raydium_timecall_clock (void):

Returns current "time".

28.9 char raydium_timecall_devrtc_rate_change (unsigned long new):

Internal, Linux only: Modifies RTC clock rate.

28.10 void raydium_timecall_devrtc_close (void):

Internal, Linux only: Will close RTC clock.

28.11 unsigned long raydium_timecall_devrtc_init (void):

Internal, Linux only: Will open RTC clock.

28.12 int raydium_timecall_detect_frequency (void):

Internal: This function will find the best timer available for current
platform, and adjust properties to your hardware (rate, divisor, ...).

28.13 void raydium_timecall_init (void):

Internal use.

28.14 int raydium_timecall_add (void *funct, GLint hz):

There is two sort of timecalls with Raydium:

1. Standard ones:

raydium_timecall_add(function,800);

void function(void) will be called 800 times per second.

2. Elastic timed ones:

raydium_timecall_add(function,-80);

void function(float step) will be called for each frame, with a
"step factor" as argument. In the above example, a 160 Hz game will call
function with step = 0.5, but step = 2.0 for a 40 Hz game.

A standard timecall will use void(void) function and a positive hertz
argument, as an elasitc one will use void(float) and negative hertz argument.

28.15 void raydium_timecall_freq_change (int callback, GLint hz):

This function changes the callback frequency. See above for possibles
values of hz (negative and positive values).

28.16 void raydium_timecall_callback (void):

Internal use (frame fired callback).

29 Network:

29.1 Bases of Raydium's networking API:

Raydium supports networking via UDP/IP, providing high level functions
for multiplayer game development.
Raydium servers are limited to 256 clients for now.

You will find in network.c a set of functions and vars dedicated to
networked games: players names, event callbacks, UDP sockets,
broadcasts, ...
All this is ready to use. As it's not done in the introduction of this
guide, We will explain here some variables defined in common.c.

#define RAYDIUM_NETWORK_PORT          29104
#define RAYDIUM_NETWORK_PACKET_SIZE   230
#define RAYDIUM_NETWORK_TIMEOUT       5
#define RAYDIUM_NETWORK_PACKET_OFFSET 4
#define RAYDIUM_NETWORK_MAX_CLIENTS   8
#define RAYDIUM_NETWORK_MODE_NONE     0
#define RAYDIUM_NETWORK_MODE_CLIENT   1
#define RAYDIUM_NETWORK_MODE_SERVER   2

Here, we can find network port declaration (Raydium will use only one
port, allowing easy port forwarding management, if needed), default timeout
(unit: second), and the three mode possible for a Raydium application.

But there is also two other very important defines: packet size
(unit: byte) and max number of clients.. This is important because
Raydium uses UDP sockets, and UDP sockets required fixed
length packets, and as you need to set packet size as small as possible
(for obvious speed reasons), you must calculate you maximum
information packet size (players position, for example), multiply
it by RAYDIUM_NETWORK_MAX_CLIENTS,and add RAYDIUM_NETWORK_PACKET_OFFSET
wich represent the required header of the packet.

It's more easy than it seems, look:

My game will support 8 players.
I will send players state with 3 floats (x,y,z).
My packet size must be: 8*3*sizeof(float)+RAYDIUM_NETWORK_PACKET_OFFSET = 100 bytes.

Please, do not change packet offset size, since Raydium will use it
for packet header.

#define RAYDIUM_NETWORK_DATA_OK     1
#define RAYDIUM_NETWORK_DATA_NONE   0
#define RAYDIUM_NETWORK_DATA_ERROR -1

This three defines are used as network functions result:

if(raydium_network_read_flushed(&id,&type,buff)==RAYDIUM_NETWORK_DATA_OK)
{
...

#define RAYDIUM_NETWORK_PACKET_BASE 10

In most network functions, you will find a "type" argument, used to
determine packet goal. This type is 8 bits long (256 possible values),
but Raydium already uses some of them. So you can use
RAYDIUM_NETWORK_PACKET_BASE as a base for your own types:

#define NORMAL_DATA RAYDIUM_NETWORK_PACKET_BASE
#define BALL_TAKEN (NORMAL_DATA+1)
#define SCORE_INFO (NORMAL_DATA+2)
#define HORN (NORMAL_DATA+3)
...

Variables:

Your own player id (0<= id <= RAYDIUM_NETWORK_MAX_CLIENTS),
read only: int raydium_network_uid;

Current network mode (none, client, server),
read only: char raydium_network_mode;

Boolean used to determine client state (connected or not), read only:
char raydium_network_client[RAYDIUM_NETWORK_MAX_CLIENTS];

example:

if(raydium_network_client[4])
draw_player(4);

Can be used by a server to send data to his clients. Read only:
struct sockaddr raydium_network_client_addr[RAYDIUM_NETWORK_MAX_CLIENTS];

Players names, read only:
char raydium_network_name[RAYDIUM_NETWORK_MAX_CLIENTS][RAYDIUM_MAX_NAME_LEN];

OnConnect? and OnDisconnect? events (server only):
void * raydium_network_on_connect; void * raydium_network_on_disconnect;

You can place your owns callbacks (void(int)) on these events, as in
this example:

void new_client(int client)
{
raydium_log("New player: %s", raydium_network_nameclient);
}
 
...
 
int main(int argc, char **argv)
{
...
raydium_network_on_connect=new_client;
...

29.2 Reliablility versus Speed:

As explained above, Raydium is using UDP network packets, and as
you may know, UDP is not a reliable protocol, aiming speed before all.
This system is interesting for sending non-sensible data, as player positions,
for example.
But Raydium's can handle more important data, using some of methods of TCP
protocol, as Timeouts, ACK, resending, ...
This TCP style packets are available thru "Netcalls".

29.3 High level API: "Netcalls" and "Propags":

Netcalls provides you a good way to handle network exchanges using
callbacks functions, like a simple RPC system.
The idea is simple, built over the notion of "type". See suitable functions for
more information about this system.

Another available mechanism is called Propags, and allows you to "share"
variables over the network (scores, game state, ...) in a very few steps.
You only need to "create" a type, and link a variable to it (any C type or
structure is allowed). After each modification of this (local copy of the)
variable, just call raydium_network_propag_refresh* and that's it. If
any other client (or the server) is applying a modification to this "type",
your local copy is automatically updated.

29.4 int raydium_network_propag_find (int type):

Lookups a "propag" by his type. Returns -1 is no propag is found.

29.5 void raydium_network_propag_recv (int type, char *buff):

Internal callback for "propag" receiving.

29.6 void raydium_network_propag_refresh_id (int i):

Will refresh a propag by his id.

29.7 void raydium_network_propag_refresh (int type):

Will refresh a propag by his type.

29.8 void raydium_network_propag_refresh_all (void):

Will refresh all propags

29.9 int raydium_network_propag_add (int type, void *data, int size):

This function will "register" a new propag. You need to provide the address
of your variable/structure (data), ans its size. A dedicated type
is also required (see at the top of this chapter).