This Function-Library is designed for Blitzbasic3D V1.90 and higher, to generate
Clouds and Clusters, based of Particles. The particle inhabits 4 polygons with a vertex at center, instead of normal particles with 2 polygons. This lets the particle appear like a smoothed pyramid, showed from top, to give him a voluminous look with vertex-lightning.
You can generate clouds with various shapes, throu meshes. Use all normal B3D Features like Textures,Blend-Modes,FX-Flags,Collision, etc. with these clouds. Split the clouds into groups to give them various attributes.
See the demo-soucrecodes how to use this functions.
shadow-demo: demonstrates the shadowing of clouds with Autolightning and different alpha-textures
cloudfield-test: shows how to use prerendered cloud-shadowing with fixed lightsources.
glowing-clouds: does the same but with using of groups to generate a glowing core.
wood: shows how to use PCL_Cloud to generate trees.
collisiontest: shows how to use PCL_ParticleType to use collisions.
savecloud and loadcloud: savecloud saves a cloud under savedcloud.txt and loadcloud loads it.
You will see, that these functions can generate a wide range of effects
Changes since Version 1.0:
Fixed: PCL_NewCloud() has slightly improved particle placing for better results.
Fixed: PCL_SetCloudShininess() appears in manual but not in the library. Sorry.
Changed: PCL_SetTempPos is no longer needed and removed.
Changed: PCL_SetCloudTexture()´s parameter changed, to store texture-flags and -modes inside the cloud-structures.
Changed: PCL_PaintParticle() was removed. It was needed. There is no way to read out B3D-Brush properties.
Changed: PCL_SetNearFade() has now the optional group-Parameter.
Added: PCL_SaveCloud() and PCL_LoadCloud() included to load former saved Clouds, i.e. as templates.
Added: PCL_UpdateCollisionZones() to update Entity´s box
and radius after use of Scaleentity for this cloud or its parent entity.
Changes since Version 2.0:
Fixed: PCL_NewCloud() was sometimes generating groups without particles.
Changed:
PCL_SetNearFade() has now optional parameter to set a fix range for
nearfading.
Changed: PCL_SetAutoFade() has now the optional group-Parameter.
Added: PCL_PointParticle() to let particle face a specific entity
Added:
PCL:CopyCloud() to copy another cloud.
Changes since Version 2.5:
Fixed: PCL_LoadCloud() was generating empty clouds, if the cloudfile was not loaded.
Fixed: PCL_SaveCloud() does not save some clouds, if more then one cloud was active.
Fixed: Some little bugs and issues.
Changed: PCL_SetCloudTexture() has now 5 optional parameters to set Texture-Geometry. Please check your code, if you use the new version.
Description: Generates a new cloud from a given shape with a specified amount of particles and returns the handle of the cloud.
| mesh: |
A valid Mesh. Do Not give an empty mesh, otherwise you will get an "Memory Access Violation". The mesh must have at least one triangle.
|
|
amount:
|
Amount of Particles between 1-200. More then 200 Particles causes an Errormessage. 0 generates an empty cloud. If you wish to have more than 200 particles per cloud, change the constant pcl_count at the top of the pcl-sourcecode |
| groups: | Splits the particles into the given amount of groups. Every group can have seperate Colors,Textures, Blend- and FX-mode,Alpha,Pickmode etc. The Number of groups is limited by the amount of particles. Default-Setting is 1. |
Description: Saves a Cloud with all groups and properties under the given filename.
Note! Texture-filenames are saved without a path. For loading, make sure that the cloud-file and textures are in the same directory.
| handle: |
Cloud-Handle |
|
file$
|
A valid path, and a file. If the file does not exist, he will be created. There is no extension reserved. Its on you, which extension you will use. |
Description: Loads a Cloud from given path and returns the Cloud-Handle. Make sure that the file is a saved cloud, otherwise reading errors will be occur.
Important! Cameras and Lights, which are former been set, are not saved. After loading they must been set again, before UpdateCloud() or UpdateClouds() is calling.
| file$: |
Cloud-Handle |
|
parent
|
Optional. This allows you to set the parent entity of Cloud. This will still result in the cloud being created at position 0,0,0 rather than at the parent entity's position. |
Description: Copies the given cloud and returns the Cloud-handle.
| handle: |
Cloud that should be copied. |
Description: Deletes a former created cloud
| handle: |
Cloud to be delete. |
Description: Scaling Cloud-Particles:
| handle: | Cloud-Handle |
| scale_min#: | Start of Scaling-Range |
| scale_max#: |
End of Scaling-Range |
|
mode:
|
Will mostly be used after PCL_NewCloud(). Move
the particle towards or away from cloudcenter with the same amount of its
own given scale. This places the scaled particles inside or outside the
border of the given Cloud-Shape. 1 = no Change. Particle-Position will be not changed. 2 = Particles will be placed inside the Cloud-Shape. 3 = Particles will be placed outside the Cloud-Shape. |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets the starting value for internal looptime for PCL_UpdateClouds(). (see below, next Command)
backDescription: Updates Light, Shadow,Pointing and Fading of all active Clouds. Use this Command in Mainloops. The Light/Shadow Calculation changes the color of Particles smoothly, during the Mainloop runs. This is not really fast enough for Realtime, so only a part of particles of one Cloud will be changed per frame. At next frame the next cloud will be done, and so on.
| 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 |
|
| 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 PCL_UpdateClouds(). Now PCL_UpdateClouds() generates his own looptime for internal use. To avoid unpredictable results at start, you should call PCL_SetTimer() before the mainloop starts. |
Description: Updates Light and Shadow for the specified Cloud. The difference to PCL_UpdateClouds() is, that the changes for all Particles immediatly are made at once and only one time per call. This tooks more time than PCL_UpdateClouds() and is not useful for Realtime. You can use this for Clouds that will not be moved or rotated or something, and when the Light stands still, so that no changes in lightning occurs. Now you can call this Command once per Cloud at start and set autolightning to 0. ( see also PCL_AutoLightning() ).
| handle: |
Cloud-Handle |
Description: Sets the "Light-Entity" for the specified Cloud.
| handle: |
Cloud-Handle |
|
light_handle:
|
Light-Entity. This Entity must not be a real B3D-Light. It can be every valid Entity. The position of this Entity gives the direction for Autolightning. Its independent from normal lightning by B3D-Lights |
| renderstep: | sets the steps between light and dark side of a cloud. Lower values are made finer steps from light to dark, but tooks more time to calculate. Useful values from 1 to 100. |
Description: Sets the Ambient Light-Level for the specified Cloud. Can be different from B3D-Ambient Light. Useful by low B3D-Ambient Light, to make Clouds lighter with Autolightning.
| handle: |
Cloud-Handle |
|
r,g,b
|
Red,Green,Blue Components of Ambient Light, between 0 and 255. |
Description: Sets the Auto Lightning for the specified Cloud.
| handle: |
Cloud-Handle |
|
auto:
|
1 or 0. Enables/Disables Light-,Darkside Calculation for this cloud,
by PCL_UpdateClouds(). |
Description: Sets the Camera for the specified Cloud.
| handle: |
Cloud-Handle |
|
camera_handle: |
A valid B3D-CameraHandle created with CreateCamera(). The position of this Camera will be needed for Nearfading and pointing |
| point: | 1 or 0. Enables/Disables, the particles faces the Camera. |
| random: | Optionally Parameter with 1 or 0. Enables/Disables, the particles faces the Camera with random z-angle. Default is set to 0. |
Description: Sets an Entity for the particles to face to.
| handle: |
Cloud-Handle |
|
entity: |
Any valid Entity-handle, to
point to. Note: you must set PCL_SetCamera(..,..,0) to disable Camera-Facing, otherwise PCL_PointParticle will have no effect, when PCL_UpdateClouds() is used. |
| random: | Optionally Parameter with 1 or 0. Enables/Disables, the particles faces the Entity with random z-angle. Default is set to 0. |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets the Nearfading for the specified Cloud.
| handle: |
Cloud-Handle |
|
nearfade:
|
0. Disables Nearfading |
|
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 |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets Autofading for the specified Cloud. This Command uses B3D Autofading for max. speed. If you like to disable it later, set both parameter to -1.
| handle: |
Cloud-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 | |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. | |
Description: Rotates all particle of the specified cloud. You´re able to set a randow value range for each axis. Remember, you must set PCL_SetCamera(..,..,0) to disable Camera-Facing.
| handle: |
Cloud-Handle |
| pitch: | sets angle for x-axis |
|
yaw:
|
sets angle for y-axis |
| roll: | sets angle for z-axis |
| r_pitch: | :random value for x-axis |
| r_yaw: | random value for y-axis |
| r_roll: | random value for z-axis |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
PCL_RotateParticle(handle,-90,0,0,0,0,90) <-let all particle show upwards with
random roll-angle
PCL_RotateParticle(handle,0,0,0,180,180,180) <-gives all particles a random
orientation
Description: Moves the partilce towards or away from cloud-center with random value between min and max value. A value of 1 means, the particle does not change his position. Lesser than 1, the particle moves towards to center, greater than 1, he moves away from center.
| handle: |
Cloud-Handle |
|
min#:
|
minimum Distance |
| max#: | maximum Distance |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets color-range for the particles between r1,g1,b1 and r2,g2,b2.
| handle: |
Cloud-Handle |
| r1,g1,b1 | sets Red,Green,Blue-component for starting color |
| r2,g2,b2 | sets Red,Green,Blue-component for end color |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description:Sets the speed, at which colors of particles will changed during Light/Shadow calculation with PCL_UpdateClouds(). A value of 1 means, that a change from white to black (FFFFFF -> 000000) needs one second. Lesser values makes it slower, greater values faster. Useful values between 0 and 2.
| handle: |
Cloud-Handle |
| speed#: |
value for Colorchange with PCL_UpdateClouds(). Default ist set to 0.5 |
Description: Sets Alpha-Range for particles between min# and max#. Useful values between 0 and 1.
| handle: |
Cloud-Handle |
|
min#:
|
minimum Alpha |
| max#: | maximum Alpha |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets Vertex-Shininess for particles between min# and max#. Useful values between 0 and 1.
| handle: |
Cloud-Handle |
|
min#:
|
minimum Shininess |
| max#: | maximum Shininess |
| group: | Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Applies textures to particles. Texture-file ,flags and blendmodes are set as seperate parameter, so PCL_cloud can store this, to save it later.
| handle: |
Cloud-Handle |
| file$: | A valid texture file, like .bmp, .jpg, .tga and .png files |
| flag: |
Optional. Set texture-flags to add effects to texture. All common B3D-texture-flags are aviable. Default is set to 1. |
| blend: |
Optional. Set texture-blend to blend with texture-layers below. All common B3D-texture-blendmodes are aviable. Default is set to 2. |
| scale_x# scale_y#: |
Optionally Parameter, to set the texture-scale . Default is set to 1 for both. |
| rot#: | Optionally Parameter, to choose the texture-rotation . Default is set to 0. |
| pos_x# pos_y#: |
Optionally Parameter, to set the texture-position . Default is set to 0 for both. |
| index: | Optionally Parameter, to choose a texture-layer between 0 and 7. Default is set to 0. |
|
group:
|
Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets Blendmode for particles like EntityBlend (Alpha/Multiply/Add ) .
| handle: |
Cloud-Handle |
| blendmode: | Blendmode of the particle. 1: Alpha (default) 2: Multiply 3: Add |
|
group:
|
Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets misc effects for particles like EntityFx. Add flags to combine effects
| handle: |
Cloud-Handle |
| flag: | 0: nothing (default) 1: full-bright 2: use vertex colors instead of brush color 4: flatshaded 8: disable fog 16: disable backface culling 32: force alpha-blending |
|
group:
|
Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Sets an EntityType and Pickmode for the particles.
The type will be used with Collisions. Example: You sets a cloud with little
particles in a wide range, with a masked texture of asteroids. Now you should
sets spheric collision with this particles.
The Pickmode and the Obscurer will mostly used with EntityVisible. Example:
You have a sun with Lensflares. If the sun is behind a Cloud, or you fly throu,
you can check with EntityVisible(), if the Lensflare should be active or not.
| handle: |
Cloud-Handle |
| type: |
Sets the collision type for an entity. A collision_type value of 0 indicates
that no collision checking will occur with that entity. A collision value
of 1-999 will mean collision checking will occur. |
| pickmode: | type of geometry used for picking: 0: Unpickable (default) 1: Sphere (EntityRadius is used) 2: Polygon 3: Box (EntityBox is used) |
| obscurer: | True to determine that the entity 'obscures' other entities during an EntityVisible call. |
|
group:
|
Optionally Parameter, to choose a specific group of particles. Default is set to 0, so all particles will be affected. |
Description: Updates the size of particles collisionbox and -radius. Mostly used after an ScaleEntity of the whole cloud. If you scale an entity, the box and radius will not scaled automatic with it. Normally you must do this manually. This Command makes it for you.
Collisionbox and -radius will also updated when PCL_SetParticleScale() is called.
| handle: |
Cloud that will be updated. |
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