BSM_Renderer V1.6 Manual:

This Function-Library is designed for Blitzbasic3D V1.90 and higher. It generates special Cubemaps to handle Dot3-Bumpmapping easier.
BSM stands for BumpmappingShadowMap. At first, some answers how it works. The functionality bases on textures with special gradients.

This gradient has the same colors and directions like a normal dot3-textur. If you combine this gradient as underlaying textur with a dot3-texture above, you get the following result.

The Light-Direction seems to be centered. Now this effect will be used by this Library.
A special texture with this gradient and an alpha-channel, will be textured on a grey sphere. The grey color around the gradient let dot3-textures appaer completely black.

Sphere is flipped, to be seen from inside. A Camera is placed at centre, to render 6 pictures at low resolution, each for any axis-direction.

These rendered pictures are given to a cubemap.

This cubemap now can be textured on every object you like. The cubemap should have the first layer. Now you can place a dot3-texture as next layer on this object. As result you get a correctly highlighted bumpmap.


Now this Library will manage this for you. You simply set a cubemap for an object. Also you can set one or more lights for this map. The same map can be used by other objects. If light-directions are changed, the cubemaps will be updated automatically.

List of Commands:

BSM_Init
BSM_Set_MainCamera
BSM_Create_Cmap
BSM_Create_Smap
BSM_Free_Map
BSM_SetLight
BSM_Set_AmbLight
BSM_Z_Offset
BSM_Set_Angle
BSM_Set_Auto
BSM_Set_Specular_Texture
BSM_Set_Specular_Color
BSM_Set_Specular_Size
BSM_Set_Updates
BSM_Update
BSM_Update_All
BSM_End
BSM_Set_Renderpos
BSM_Debugger

Additional Commands:

BSM_Make_Specular
BSM_Dot3_to_Gloss
BSM_Create_ColorTexture

BSM_Set_TextureColor
BSM_Free_ColorTexture


Changes in V1.6

Added: BSM_Set_AmbLight
Added: BSM_Create_ColorTexture
Added: BSM_Set_TextureColor
Added: BSM_Free_ColorTexture
Fixed: Helper-Objects for Specular-Mapping changed for better simulating colored multiple lights, for bumpmapped objects.

Changes in V1.5

Specular-Cubemaps are added to generate Glossmapping and shiny spots on any surface.
Added: BSM_Create_Smap
Added: BSM_Set_Specular_Texture
Added: BSM_Set_Specular_Color
Added: BSM_Set_Specular_Size
Added: BSM_Make_Specular
Added: BSM_Dot3_To_Gloss
Added: BSM_Set_Updates for better control of performance.
Changed: BSM_Free_Cmap was renamed in BSM_Free_Map. This Command will now used for both sorts of Cubemaps.
Fixed: Some minor bugs. Sligtly increased performance.


BSM_Init ( texturefile )

Description: Initialise the BSM_Library. You must give the texture, that will be rendered into the BSM-Cubemaps.

texturefile:
The texture with the special gradient, above i have written about. One of this textures are in the archive.

back

BSM_Set_MainCamera ( camera )

Description: Gives your main camera to the Library. This camera must be hided, if the BSM-Cubemaps will be updated. Later the camera must be shown again, to render your own scene. You can handle this by yourself or let manage this through the Library. Its your choice.

camera:

Must be the camera, that is used by your own program.

back



BSM_Create_Cmap (object , [flag] , [layer])

Description: Creates a BSM-Cubemap an returns the texture-handle.

object:

The object that will get the BSM-Cubemap. Objects position and direction, relative to the light(s) is necessary to adjust the BSM-Cubemap correctly.

flag:
Optionally. If set to 1, the object will be textured with the BSM-Cubemap. Also you can do this by yourself. Default is set to 0
layer Optionally. This layer-number will be used to texture the BSM-Cubemap. Default is set to 0

back


BSM_Create_Smap (object , [size] , [flag] , [layer])

Description: Creates a Specular-Cubemap an returns the texture-handle.

object:

The object that will get the Specular-Cubemap. Objects position and direction, relative to the light(s) is necessary to adjust the Specular-Cubemap correctly.

size: Optionally. Sets the texture-size for this Specular-Cubemap. Default is 256x256 pixel.
flag:
Optionally. If set to 1, the object will be textured with the Specular-Cubemap. Also you can do this by yourself. Default is set to 0
layer Optionally. This layer-number will be used to texture the Specular-Cubemap. Default is set to 0

back


BSM_Free_Map ( handle )

Description: Deletes a former created BSM-Cubemap or Specular-Cubemap. If the Cubemap is given to an Object, this Layer will be left on it. But the Cubemap cannot longer changed.

handle:

A valid BSM-Cubemap handle or Specular-Cubemap.

back


BSM_SetLight (handle , light , number , [type] , [luminance#])

Description: Sets a Lightsource for this BSM-Cubemap or Specular-Cubemap. The relative position and direction between the lightsource and the object which is given for the BSM-Cubemap, will be used to align the BSM-Cubemap.

handle:

A valid BSM-Cubemap handle or Specular-Cubemap.

light: The object, that should be the lightsource. Must not be a valid B3D-Light
number: The number of this light for this BSM-Cubemap. Maximum numbers of lights per BSM-Cubemap is set by the Constant "bsm_lights", default is set to 8.
type:

Optionally. Type of light. 1= directional light. 2= point light. Default is set to 2

luminance#: Optionally. Set the intense for this light between 0 (0%) and 1 (100%). Default is set to 1
back

BSM_Set_AmbLight (handle , light#)

Description: Sets the ambient Lightlevel for this BSM_Cubemap. A value greater 0 results in fading the Cubemap-Background from grey to blue. This affects a Bumpmap to lighten along its Z-Axis Vector, everywhere except the areas where occurs lighting by the lightsources.

handle: A valid BSM-Cubemap handle.
light#:

Value between 0 and 1

back

BSM_Z_Offset (handle , angle#)

Description: The BSM_System has only one restriction. The BSM-Cubemap and the dot3-texture should have the same align. When you rotate the dot3-texture, bumpmapping looks a little bit freaky.

Here are BSM-Cubemap and dot3-texture both upright. On this sphere the dot3-texture is rotated about 180 dergrees. The sphere and the texture seems to get her light from different directions.

The Library can compensate z-angle differences between BSM-Cubemap and the given object ( i.e. the sphere above), but not a rotated dot3-texture. With this command you can set an offset-angle to compensate those effects.

handle: A valid BSM-Cubemap handle.
angle#:

Angle between 0 and 360 degrees. For the example above you should set 180 degrees to restore the correct bump-mapping.

back

BSM_Set_Angle (handle , angle#)

Description: Sets the minimum angle where the Library will update the BSM-Cubemap. If object or light changes here positions or light-direction ( for directional light) changes, the BSM-Cubemap will be updated, when the difference reaches the minimum angle. Angle can be set for every BSM-Cubemap separate. Default is set to 1 degree.

handle: A valid BSM-Cubemap handle or Specular-Cubemap.
angle#:

Angle between 0 and 360 degrees.

back

BSM_Set_Auto( handle , flag)

Description: Sets Auto-updating for this BSM-Cubemap. If set to 0 you must update this BSM-Cubemap manually when light or object are moved or rotated.

handle:

A valid BSM-Cubemap handle or Specular-Cubemap.

flag: Enables/Disables automatic updating for this BSM-Cubemap.
back

BSM_Set_Specular_Texture (handle , lightnumber , texture)

Description: Sets a Texture for a specified lightnumber for this Specular-Cubemap.

handle:

A valid Specular-Cubemap.

lightnumber: The light that will get this texture
texture: A former loaded or created texture
back

BSM_Set_Specular_Color (handle , lightnumber , r , g , b )

Description: Sets a color for a specified lightnumber for this Specular-Cubemap.

handle:

A valid Specular-Cubemap.

lightnumber: The light that will be colored
r,g,b: Red , Green and Blue Components
back

BSM_Set_Specular_Size (handle , lightnumber , scalex# , scaley# )

Description: Sets a size for a specified lightnumber for this Specular-Cubemap.

handle:

A valid Specular-Cubemap.

lightnumber: The light that will be sized.
scalex# , scaley#: x and y size for this light.
back

BSM_Set_Updates ( amount )

Description: Sets the maximum amount of updates, taken with BSM_Update_All ( ) , per frame ( or loop ). This will save performance and avoid to let the library update to many Cubemaps at the same frame.

handle:

A valid BSM-Cubemap handle or Specular-Cubemap.

back

BSM_Update ( handle , [flag])

Description: Updates the given BSM-Cubemap. Degree which are set with BSM_Set_Angle will be ignored. Useful when objects and light are not changed during mainloop, so you can update the BSM_Cubemap once, before mainloop starts.

handle:

A valid BSM-Cubemap handle or Specular-Cubemap.

flag: Optionally (1/ 0). Enables/Disables, if main camera should be hide before and shown by the Library, after updating the BSM-Cubemap. Default is set to 0.
back

BSM_Update_All ( [flag] )

Description: Updates all BSM-Cubemaps. Degree which are set with BSM_Set_Angle will used. The command should be used in mainloop, before Renderworld() is called. If BSM_Debugger is activated this function returns the amount of updated BSM-Cubemaps.

handle:

A valid BSM-Cubemap handle or Specular-Cubemap.

flag: Optionally (1/ 0). Enables/Disables, if main camera should be hide before and shown by the Library, after updating the BSM-Cubemaps. Default is set to 0.
back

BSM_End( )

Description: Clears all BSM-Cubemaps and Specular-Cubemaps and frees all memory used by the Library.
Note: Cubemaps which are given to objects are left on this objects, but cannot longer changed.
Hint: If you have a static scene which is never changed ( including lights! ) after creating, you can set all BSM-Cubemaps you need, update them and texture the object with them. Now you can call BSM_End() and the Library needs no longer Processor-time and memory.

back

BSM_Set_Renderpos( x , y , z )

Description: BSM uses one ore more textured Spheres and a camera to render the BSM-Cubemaps. They must positioned and shown somewhere into the scene. No other object should placed at this position. Default is set 0,1000000,0

x , y , z

Position where the BSM_Helpers are placed to render.

back

BSM_Debugger ( flag )

Description:Enables BSM intern Debugger-Function. He returns detailed Error-Messages.

flag:

0 = Debugger disabled
1 = Runtime-Error Message will be generated and program ends
2 = Error-Message will be written into the Debuglog
3 = Error-Message will be written into the Debuglog and program is stopped.

 
back

BSM_Make_Specular ( [size] , [flag] , [mode] , [start#] , [frequency#] , [min#] , [max#] )

Description: Generates a texture with a radial Wavepattern, to use as specular spotlights. Useful when no other similar textures are aviable. All parameters are optionally. If no parameter is set, a diffuse glowing particle will be generate.

bsm_make_specular()
bsm_make_specular(128,9,1,0.5,1,0.25,1)
bsm_make_specular(128,9,0,0,1,0,1)
bsm_make_specular(128,9,2,0,0.5,0,1)

 

size:

Texture-size like 64,128 and so on. Default is 256

flag: All B3D Textureflags can be set. Default is set to 1+8
mode: Selects the used waveform for the pattern. 0=sinus 1=linear 2=rectangle. Default is 0
start#:

Starting value for the waveform. Default is set to 0

frequency#: How many waves will be drawn. Default is set to 0.5
min#:

minimum luminance for the wave. Default is 0

max#: maximum luminance for the wave. Default is 1
back

BSM_Dot3_To_Gloss (texture , [mode] , [new] , [flag] )

Description: Converts a normal Dot3-Bumpmap in a special Dot3-Bumpmap, wich is useful for Glossmapping, with the Specular-Cubemaps of this Library. See the examples.

a normal Dot3-Texture
the converted Gloss-Texture

The algorithm use the blue channel of the Bumpmap to get a greyscale pattern. This will be faded to red and green. This texture can now used as Glossmap. The texture must lay as Bumpmap ( Blendmode 4) above a Specular-Cubemap on a object. Now change the color of the specular spotlights to force various effects on the Glossmap.

texture:

A former loaded texture that will be converted

modet: sets accuracy of the algorithm. 0=single pass 1= double pass, produces better results, but tooks more time. Default is 1
new: If set to 1 a new texture will be created and the handle will be returned, default is set to 1.
flag:

All commen B3D Textureflags can be set. Default is set to 1+8.

back

BSM_Create_ColorTexture ( r , g , b , [flag] )

Description: Creates a single pixel texture with the given RGB Value and returns its handle. This Textures are useful to simulate colored light for bumpmapped objects without using DirectX-Lights and seperate objects.

r,g,b:

Red, green and blue value for this texture.

flag:

All commen B3D Textureflags can be set. Default is set to 1

back

BSM_Set_TextureColor ( texture, r , g , b )

Description: Sets a new color for this texture without recreate her.

texture:

A former with BSM_Create_ColorTexture created texture.

r,g,b:

New red, green and blue value for this texture.

back

BSM_Free_ColorTexture (texture )

Description: Deletes a former with BSM_Create_ColorTexture created texture.

texture:

A former with BSM_Create_ColorTexture created texture.

back

This Library is freeware. Use this functions at your own risk. You can use this with your own commercial and noncommercial projects. Some Credits in your projects would be nice but not necessary. You´re freely to spread this product as freeware. Its not allowed to sell it or distibute it with software-collections. Its also not allowed for you to change the contents of this .zip file and place it your own Webspace for download. Do this only with the original archive. Changes are only made by me.

Do you have Bug Reports or Feature request, please mail me. ( see below )

Having Fun with it.

Shodan

www.selfmadegames.de

heinz-helge@gmx.de