Preamble

The target of this library is to provide a shadow system for blitz3d in order to do scenery.

The name of the library is GOM

G = Gestion ( management)

OM = Ombres ( shadow)

This library can not replace a light mapping tool or a professional system. It is just a simple shadow library for BLITZ3D.

Please read carefully the recommendations before to start a project with this library.

This library is under GPL licence.

You can use as you want : for commercial or non commercial project.

If you improve it please send the update to Philippe C.

Préambule

Le but de cette librairie est de proposer un système d'ombre pour Blitz3D dans le cadre de scène.

Le nom de cette librairie est GOM

G = Gestion ( management)

OM = Ombres ( shadow)

Cette librairie ne peut remplacer un light maper ou un système professionnel. Il s'agit juste d'une simple librairie d'ombre pour BLITZ3D.

Veuillez lire attentivement les recomendations avant de commencer un projet avec cette librairie.

Cette librairie est dans le domaine gratuit.

Vous pouvez l'utiliser comme vous le souhaitez, pour un projet commercial ou non.

Si vous souhaitez l'améliorer, veuillez adresser la mise à jour à Philippe C.

Recommendations

Use this library to manage shadow in a small scenery :

• main scenery : 10000 triangles

This is the ground , mountain, house where your character will move.

• 5 – 10 moving 3D objects with shadow

This object could be : other characters, car, tree (with wind) ...

• use a light mapper for the fixed objects and the scenery.

• If you want to use moving light as alternate of day/night or lamp , etc. ... Make test and adapt you scenery in function of the constraints of GOM

Have a look on the demo to understand what is feasible with this library.

Recommendations

Utilisez cette librairie pour utiliser les ombres dans de petite scène :

• scène principale : 10000 triangles

Il s'agit du sol, montagnes, maison... Où vos personnages vont se déplacer.

• 5 – 10 objets 3D animés avec des ombres

Ces objets peuvent être : autre personnage, voiture, arbres (avec le vent) ...

• utiliser un light mapper pour les objets fixe de la scène.

• Si vous souhaitez utiliser des lumières mouvantes, comme pour alterner le jour ou la nuit ou une lampe, etc... Faites des testes et adaptez votre scène aux contraintes de GOM.

Regardez les démo pour comprendre ce qui est faisable avec cette librairie.

How to proceed if you are a novice with GOM ?

1. Design the scenery , the 3D object, the texture ...

2. Build your scenery and the game play first.

When you have a playable scenery you can implement the shadow with GOM

3. Add GOM command to your game.

Note : if you are not able to do the step 1 & 2 don't try the step 3 . Use the demo and 3D model provided to understand what 3D model means. And understand how a playable scenery is done .

When you are able to update the demo and get the expected result . At this step you can use GOM in you own playable scenery.

Comment procéder si vous êtes un novice avec GOM ?

3. Mettez au point la scène, les objets 3D, les textures...

4. Construisez la scène et le game play d'abord.

Lorsque vous avez une scène jouable vous pouvez implémenter les ombres avec GOM

3. Ajouter GOM à votre jeu.

Note : si vous n'êtes pas capable de faire les étapes 1&2 il est inutile de faire l'étape 3. Utilisez les démo et les modèles 3D fournit pour comprendre ce qui signifie modèle 3D. Et comprenez comment une scène jouable est faite.

Lorsque vous êtes capable de modifier les démos et d'obtenir le résultat escompté, vous pouvez utiliser GOM dans vos propre scène.

All the generalities above are detailed in next chapters

Toutes les généralités ci dessus sont détaillées dans les chapitres suivants.

TBD

A FAIRE

TBD

A FAIRE

1. Include the library

2. You have to add the 'GOM_' prefix to the following blitz3D commands only for the 3D objects with dynamic shadows managed by GOM : see BLTZ3D help for more information on the function below ( the syntaxes is the same than with blitz3d)

Animate

CameraRange

CopyMesh

CreateCamera

CreateCone

CreateCube

CreateCylinder

CreateLight

CreateMesh

CreateSphere

FreeEntity

LightColor

LightConeAngles

LightRange

LoadAnimMesh

LoadBSP

LoadMesh

LoadMD2

MeshWidth

MeshHeight

MeshDepth

ScaleEntity

ScaleMesh

For the 3D objects with shadows done with light mapper do not add the 'GOM_' prefix.

3. Add the GOM functions ( see chapter 5 for more detailed information ) :

GOM_sceneCreate : in order to identify the scenery

Or set optional parameter in order to improve the shadow generation : reference chapter 5 and demoxx

4. Before the main loop add the following function :

GOM_scenePrepare(startScene)

5. In the main loop add the following function :

...

UpdateWorld()

...

GOM_sceneShadow(player,camera)

...

RenderWorld

...

3. Inclure la librairie

4. Vous devez ajouter le préfixe 'GOM_' aux commandes suivantes uniquement pour les objets 3D ayant des ombres dynamiques gérées par GOM : référez vous à l'aide de BLITZ3D pour plus d'informations sur les fonctions ci dessous (la syntaxe est la même)

Animate

CameraRange

CopyMesh

CreateCamera

CreateCone

CreateCube

CreateCylinder

CreateLight

CreateMesh

CreateSphere

FreeEntity

LightColor

LightConeAngles

LightRange

LoadAnimMesh

LoadBSP

LoadMesh

LoadMD2

MeshWidth

MeshHeight

MeshDepth

ScaleEntity

ScaleMesh

Pour les objets 3D ayant leurs ombres faites par light mapper ne pas utiliser le préfixe 'GOM_'.

3. Ajoutez les fonctions GOM (voyez le chapitre 5 pour plus d'informations) :

   GOM_SceneCreate : utilisé pour identifier la scène.

   Ou régler certains paramètres optionnels dans le but d'améliorer la génération d'ombre : voir chapitre 5 et demoxx

4. Avant la boucle principale ajoutez la fonction suivante :

GOM_scenePrepare(startScene)

5. Dans la boucle principale ajoutez les fonctions suivantes :

...

UpdateWorld()

...

GOM_sceneShadow(player,camera)

...

RenderWorld

...

GOM_sceneCreate(object3d%,red%,green%,blue%) : mandatory

This function should be used to identify the ground where the character/player walk, run.

It is possible to have several ground in the same scenery . For instance a land and a house with several floor ( see demo04.bb ).

These objects will be called in the documentation scenery

Object3d : unique blitz identifier returned by the function GOM_... used to create or load a 3D object .

Red,green,blue : colour of the ambient light

GOM_sceneCreate(object3d%,red%,green%,blue%) : obligatoire

Cette fonction doit être utilisée pour identifier le sol ou le joueur/personnage marche, cour.

Il est possible d'avoir plusieurs sol dans la même scène. Par exemple un paysage et une maison ayant plusieurs niveau (voir démo04.bb)

Ces objets seront appelés dans la documentation de la scène.

Object3d : identifiant unique blitz retourné par les fonctions GOM_... utilisées pour créer ou charger des objets 3D.

Red,green,blue : couleur de la lumière ambiante.

GOM_sceneObjectAll(object3d%) : mandatory

This function should be used in order to identify the object which can move between different scene , for instance : the player

Object3d : unique blitz identifier returned by the function GOM_... used to create or load a 3D object .

GOM_sceneObjectAll(object3d%) : obligatoire

Cette fonction doit être utilisé afin d'identifier les objets pouvant se dépacer d'une scène à l'autre, par exemple : le joueur.

Object3d : identifiant unique blitz retourné par les fonctions GOM_... utilisées pour créer ou charger des objets 3D.

GOM_scenePrepare(object3d%) : mandatory

This function prepare the sceneries in order to optimise the shadow computation and check if all the scenery is consistent. This should be done in order to identify the starting point of the player. On which place the player is.

If an error is detected an error message will be displayed and the program stop.

Object3d : unique blitz identifier returned by the function GOM_... used by the function GOM_sceneCreate(object3d).

GOM_scenePrepare(object3d%) : obligatoire

Cette fonction prepare la scène afin d'optimiser le calcul d'ombre et vérifie si la scène est cohérente. Elle doit être appelée afin de déterminer le point de départ du joueur, dans quel scène je joueur est.

Si une erreur est détectée un message d'erreur s'affichera et le programme s'arrêtera.

Object3d : identifiant unique blitz retourné par les fonctions GOM_... utilisées pour créer ou charger des objets 3D.

GOM_sceneShadow(collision%,player%,camera%) : mandatory

This function computes the shadows for all the sceneries.

Collision is the blitz3D identiifer of the pivot used to manage the collision

Player is the blitzt3D identifier of the main character under the player control.

Camera is the blitzt3D identifier of camera used in the scenery.

GOM_sceneShadow(collision%,player%,camera%) : obligatoire

Cette fonction calcule les ombres pour toutes les scènes.

Collision est l'identifiant Blitz3D du pivot utilisé pour gérer les collisions.

Player est l'identifiant Blitz3D du personnage principale sous le controle du joueur.

Camera est l'identifiant Blitz3D de la camera utilisée dans la scène.

GOM_textureSize(idobject%,size%) : optional

This function change the texture size of an object created with the GOM functions relatives to the 3D object creation ( see chapter 4 for more information)

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

Size : is the texture size use to render the shadow , by default it is set to 128. The texture size could be 64,128,256 , you can use more but the performance will be really poor. The best compromise is 128

GOM_textureSize(idobject%,size%) : optionnel

Cette fonction change la taille de la texture d'un objet crée avec les fonctions GOM relatives à la création des objets 3D (voir chapitre 4 pour plus d'information)

idObject : identifiant unique Blitz d'un objet 3D crée ou chargé avec les fonctions GOM_BLITZ3D

Size : taille de la texture utilisée pour rendre l'ombre, initialisé par défaut à 128. La taille de la texture peut être 64, 128, 256, le plus grand, le plus lent ce sera. Le meilleur compromis est 128.

GOM_zoomSize(idobject%,zoom#) : optional

This function change the zoom of the camera of a shadowed object created with the GOM functions relatives to the 3D object creation ( see GOM_BLITZ3D function for more information)

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

Zoom : is a real number used to set the zoom , star at 0.1 to see the result and decrease the value until the shadow is complete.

GOM_lightHeigthMin(idlight,yMin%) : optional

This function set the minimum hight of the light when the light move , by default it is the y position of the light when the game start

idlight : identifier of the light created with GOM_CreateLight

yMin : minimum hight of the light when the light move , for instance at sunrise or at sunset.

See demo 3 for more information

GOM_sceneTitle(idObject%,title$) : optional

This function could be used in order to give a title to the object , this title is displayed when an error occurs ( see debuglog or blocking message)

GOM_lightShadowMin(idLight%,light) : optional

This function could be used to tune the shadow darkness of the a light. By default the value is set to 200.

idlight : identifier of the light created with GOM_CreateLight

light : intensity of the shadow , if the value is equal to 0 the shadow will be fully dark . If the value is closed from 255 the shadow will be light grey..

GOM_shadowheight(idObject%,height%) : optional

This function should be used in closed environment in order to avoid that the shadow is displayed on the ceil.

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

Height : is a number used to set the maximum height of a shadow when the shadow is projected on a wall for instance or a vertical object in general.

GOM_sceneObjectSurface(idobject,surface) : optional

This function should be used when a scene is composed with several surfaces ( but default only the 1^st one is taken into account)

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

Surface : number of the surface used to compute and project the shadow

.

GOM_shadowTime(idobject,time) : optional

This function should be used when the generation of the shadow is too slowed or too fast (performance)

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

Time : time in milliseconds . During this period of time the shadow is not computed , by default it is set to 200 milliseconds. 10 milliseconds should used in order to get a very good result. To use with the player or object moving very often.

GOM_shadowNO(idobject1,idobject2) : optional

This function should be used when parasite projected shadows appear or to improve general performance of projected shadows. The shadow of the object1 is never projected on the object2.

idObject1, idObject2 : are the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

In order to better understand the use of this command put in comment the lines with this command in the demo04.bb.

GOM_objectCreate(file$,idObject,parent,control=true)

This function could be used instead of the blitz command relative ti the 3D objet creation.

CopyMesh, CreateCone ,CreateCube, CreateCylinder, CreateMesh, CreateSphere, LoadAnimMesh, LoadBSP, LoadMesh, LoadMD2.

file : name of the file used to load the 3D object it is manadatory to compute correctly the meshHeight, the mesWidth and the meshDepth.

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

Parent : s the unique blitz identifier of a parent object created BLITZ3D functions.

Control : if true the file$ is contolled if false no control are done.

GOM_objectDelete(idObject)

This function could be used instead of the blitz command freeentity , if the command GOM_objectCreate is used , this command should be used.

idObject : is the unique blitz identifier of an 3D object created or loaded with the GOM_BLITZ3D functions.

The GOM_api_... : should not be used , it can change in the next release of the library.