Introduction, basic vars quick view

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.

1. 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 :)

2. 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.

3. 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.

4. 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 index.c says:



You 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)

5. 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.

6. Vertices

Vertices data structure is distributed in 4 parts:

1. raydium_vertex_* : these tables will simply contains vertices coordinates
2. raydium_vertex_normal_* : vertices normals. Raydium will maintain two distinct normal tables, and this one will be used for calculations.
3. 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.
4. 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.

7. 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.

8. 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.

9. 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.

10. 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.

---

Return to RaydiumApiReference index.

---