DST_Dust Manual:

This Function-Library is designed for Blitzbasic3D V1.90 and higher, to generate local or global fields of dust, like desert-storms, starfields etc.

At start, you creates simply a Dust-object. Every Dust-object has a center, that can be manipulated like every B3D-Entity.
You can assign zones to this object, as many as you like. Every zone has seperate radius and parameters for the particles.
If your camera crosses one or more zones, particles will be placed in flight-direction and removed behind the camera. For example, a starship flyes through a starfield.


The particles of a Dust-object are linked with it as childs. You can also move or rotate the Dust-object to get the same result.
For example a person stands in sand-storm.

Zones can be linked with the Dust-object, to move with it.
Note: Particles are only moving, when the Dust-object moves or rotates. If you move a Dust-zone the particles stand still. The particles still appear around the camera when the zone is overlapping camera´s position, and disappear when zone is leaving the camera.

Dust-zones can overlapping to mix particle-parameter. By setting an higher priority to zones, overlapping results in clamping out zones with lower priority.

List of Commands:

DST_Create_Dust
DST_Create_Dustzone
DST_Free_Dust
DST_Free_Dustzone
DST_Change_Camera
DST_Set_Intervall
DST_CheckZones
DST_SetTimer
DST_Update
DST_Set_Zoneradius
DST_Set_DustStatus
DST_Set_DustZoneStatus
DST_Set_DustZonePriority
DST_Set_Dense
DST_Set _Texture
DST_Set_TextureBlend
DST_Set_TextureScale
DST_Set_ColorRange
DST_Set_ScaleRange
DST_Set_AlphaRange
DST_Set_FadingFar
DST_Set_FadingNear
DST_Set_FX
DST_Set_Blend
DST_Set_SpeedBlur
DST_Set_Angle
DST_Set_Rotation

DST_Create_Dust( camera , amount , [type] )

Description: Generates a new Dust-object with a specified amount of particles and returns the handle of the Dust-object.

camera:

A valid Entity-Handle. All calculations for this Dust-object,like pointing fading etc., are assigned to this Entity. Must not be a camera, but its useful.
 
amount:
 Amount of Particles for this Dust-object. The only limit is your RAM
 
type: Optionally .Sets the particle-type. A value of 0(default) generates particles with 2 triangles. If you set type to 1, particles with 4 triangles and special aligned Vertex-normals will be generated. This let the particles appear rounded and voluminous, if you use vertex-lightning.
 
back

DST_Create_Dustzone( dust-handle , [linked] )

Description: Generates a new Zone for a former created Dust-object

dust-handle:

Dust-object Handle

linked
 Optionally. Set to 1 if you wish, the zone will become a child of the Dust-object. Default is 0
back

DST_Free_Dust( dust-handle )

Description: Deletes a former created Dust-object with all particles and zones

dust-handle:

Dust-object Handle

back

DST_Free_Dustzone( zone-handle )

Description: Deletes a former created Dust-Zone. Only this zone will be deleted, no particles or Dust-objects

zone-handle:

Dust-zone that should be delete.
back

DST_Change_Camera ( dust-handle , camera )

Description: Changes the former given camera for this Dust-object.

dust-handle: A valid Dust-zone handle
camera: A valid B3D-Entity handle. Must not be a camera, but its useful.
back

DST_Set_Intervall( time )

Description: Sets the intervall in milliseconds, which is used to check out how many zones overlapping the camera. If you have big zones and slow cameras you can increase the intervall to save time and increase your FPS. You can disable automatic zone-check, when you set time = -1. Default is set to 30 ms

time:

time in milliseconds between two zones-camera checks
back

DST_CheckZones()

Description: Checks the Distance between cameras and all Dust-zones of all Dust-objects. Calculates lists of overlapping zones at camera position, sorts out zones with lower priority and so on. DST_Checkzones() will be called within DST_Update() every x millisecs(). x is set by DST_Set_Intervall(). You should call it manually, when intervall is set to -1 (disabled).

back

DST_SetTimer()

Description: Sets the starting value for internal looptime for DST_Update(). (see below, next Command)

back

DST_Update([looptime#])

Description: Updates Placing,Pointing and Fading of all particles of all active Dust-objects. Use this Command in Mainloops.

looptime#:

Optionally. This is a special value with the amount of time in seconds, that the last frame has needed to be done. See the Example.
Code:

 
 

time=Millisecs() <-sets the starting value
While Keyhit(1)=0 <-begin Mainloop
looptime#=(Millisecs()-time)/1000.0 <-calculate time between this point and the last call of Millisecs()
time=millisecs() <-stores the actual time for the next frame
;doing your stuff
MoveEntity cube,0,0,100*looptime# <- moves the cube 100 units per second forward
If c<255
c=c+100*looptime# : EntityColor cube,c,c,c <-rises the color of the cube in 2,55 seconds from 0 to 255
Endif
Renderworld()
Flip
Wend
  The variable looptime# stores now the time, the mainloop has needed for one frame, in seconds. Now you can use this to make all motions, rotations, simply all changes timebased,that done during the loop runs . All changes now independent from the FPS.
If you don´t use those system, type simply DST_Update(). Now DST_Update() generates his own looptime for internal use. To avoid unpredictable results at start, you should call DST_SetTimer() before the mainloop starts.
back

DST_Set_Zoneradius( zone-handle , radius# )

Description: Sets a new radius for the specified Dust-zone

zone-handle: A valid Dust-zone handle
radius# :

New radius for this zone
back

DST_Set_DustStatus( dust-handle , flag )

Description: Activates or deactivates the specified Dust-object. If an Dust-object is inactive, no zones and particles will be calculated or shown. Every created Dust-object is active by default.

dust-handle: A valid Dust-object handle
flag:

0 = Dust-object is inactive ; 1 = Dust-object is active
back

DST_Set_DustZoneStatus( zone-handle , flag )

Description: Activates or deactivates the specified Dust-zone. If an Dust-zone is inactive, all calculation for this zone will be stopped. Every created Dust-zone is active by default.

zone-handle:

A valid Dust-zone handle
flag:

0 = Dust-zone is inactive ; 1 = Dust-zone is active
back

DST_Set_DustZonePriority( zone-handle , priority )

Description: Sets a new priority for this Dust-zone.

zone-handle: A valid Dust-zone handle
priority:

an integer value for the zone-priority
back

DST_Set_Dense( zone-handle , dense# )

Description: Sets the particle density for this Dust-zone. The value ranges from 0 to 1. 0 means 0% and 1 means 100% of max. amount of particles of the Dust-object, which inhabits this Dust-zone. For example: the Dust-object has created with 200 particle and you set density for this Dust-zone to 0.5, max. 100 particle will be used, when the camera crosses this Dust-zone

zone-handle:

A valid Dust-zone handle

dense#:
 A value between 0 and 1
back

DST_Set_Texture(zone-handle , file$ , flag )

Description: Sets the texture that particles will have when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle

file$: path and filename of a valid texturefile like .bmp .jpg .png .pcx .tga
flag: all common B3D texture-flags can be set
back

DST_Set_TextureBlend( zone-handle , blendmode )

Description: Sets the texture-blendmode for the former specified texture for this Dust-zone.

zone-handle:

A valid Dust-zone handle
blendmode: all common B3D Texture-Blendmodes can be set
back

DST_Set_TextureScale( zone-handle , scale_u# , Scale_v# )

Description: Sets the texture-scalefactor for the former specified texture for this Dust-zone.

zone-handle:

A valid Dust-zone handle
scale_u#:
Scale-factor for textures u-axis
scale_v#: Scale-factor for textures v-axis
back

DST_Set_ColorRange( zone-handle , red1 , green1 , blue1 , red2 , green2 , blue2 )

Description: Sets the color-range that particles will have when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle
red1: sets Red-Component for starting color of color-range
green1:
sets Green-Component for starting color of color-range
blue1: sets Blue-Component for starting color of color-range
red2: :sets Red-Component for end color of color-range
green2: sets Green-Component for end color of color-range
blue2: sets Blue-Component for end color of color-range
back

DST_Set_ScaleRange(zone-handle , min# , max# )

Description: Sets the range of size that particles will have when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle
min#:
 minimum Particle-Size
max#: maximum Particle-Size
back

DST_Set_AlphaRange(zone-handle , min# , max# )

Description: Sets the range of transparency that particles will have when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle
min#:
 minimum Particle-Alpha
max#: maximum Particle-Alpha
back

DST_Set_FadingFar( zone-handle , near# , far# )

Description: Sets the range for Autofading that particles will have when the camera crosses this Dust-zone. The value at far# is also the distance where particle being placed and removed. Default is set between 80 and 100

zone-handle:

A valid Dust-zone handle
near#:
distance in front of the camera at which particles will start being faded
far#: distance in front of the camera at which particles will be invisible
back

DST_Set_FadingNear( zone-handle , near# , far# )

Description: Sets the range for Nearfading that particles will have when the camera crosses this Dust-zone. NearFading lets the particle fading out when minimum distance is reached. By default NearFading is disabled.

zone-handle:

A valid Dust-zone handle
near#:
distance in front of the camera at which particles will be invisible
far#: distance in front of the camera at which particles will start being faded

back

DST_Set_FX( zone-handle , flag )

Description: Sets the EntityFX-flags, that particles will have when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle
flag:
 all common EntityFX-flags can be set.
back

DST_Set_Blend( zone-handle , blendmode )

Description: Sets the EntityBlendmode, that particles will have when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle
blendmode:
 all common EntityBlendmodes can be set.

back

DST_Set_SpeedBlur( zone-handle , value# )

Description: Sets the factor, how much particles will be scaled along the relative flight-direction of the camera. Every frame, the distance between the old and new position of the camera relative to the Dust-object, will be checked to calculate the relative speed and direction of the camera. This speed and the given value will be used to scale the particles. This results in longer particles at higher speed. For example: value#=10. When the relative speed reaches 10 units per second, the particles will scaled 2x along the relative Flight-direction. Its useful for star-fields like in Star-Trek.
0 disables SpeedBlur ( default ).

zone-handle:

A valid Dust-zone handle
value#:
 a value greater then 0
back

DST_Set_Angle( zone-handle , min# , max# )

Description: Sets the range of angles, that particles will have when the camera crosses this Dust-zone.

handle:

Cloud-Handle

min#:
 min. angle
max#:
 max. angle
back

DST_Set_Rotation( zone-handle , min# , max# )

Description: Sets the range of degrees, that particles will rotate when the camera crosses this Dust-zone.

zone-handle:

A valid Dust-zone handle
min#:
 min. degrees/second
max#:
 max. degrees/second
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 the changed archive on 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