GRAPHICS: 3D particles utilities

Data Structures
struct	PARTICLE
	Structure of a single particle. More...
struct	PARTICLE_EMITTER
	Structure of a particle emitter. More...
struct	PARTICLE_SYSTEM
	Structure of a particle system. More...

Macros
#define	BITMAP_PART   8
	bitmap particle
#define	CIRCLE_PART   6
	circle particle
#define	FIRE_PART   4
	fire particle
#define	NORMAL_PART   0
	classic moving particle
#define	PIXEL_PART   7
	pixel particle
#define	SINUS_PART   1
	sinus based moving particle
#define	SNOW_PART   3
	snow particle
#define	STAR_PART   5
	star particle
#define	TEXT_PART   9
	bitmap particle
#define	TRANS_PART   2
	transparent particle

Functions
PARTICLE_EMITTER *	add_emitter (PARTICLE_SYSTEM *psys)
	add a new emitter to the particle system.
int	add_particle (PARTICLE_SYSTEM *psys, int spr, int mode, int lifetime, int size, ALLEGRO_COLOR color, PHYSICS object)
	add a particle to the system
int	add_particle_at (PARTICLE_SYSTEM *psys, int spr, int mode, double px, double py, double pz, int lifetime, int size_start, int size_end, ALLEGRO_COLOR color_start, ALLEGRO_COLOR color_end, double vx, double vy, double vz, double ax, double ay, double az)
	add a particle at an absolute world position (not relative to psys->source)
int	add_particle_ex (PARTICLE_SYSTEM *psys, int spr, int mode, int off_x, int off_y, int lifetime, int size, ALLEGRO_COLOR color, double vx, double vy, double vz, double ax, double ay, double az)
	add a particle to the system (extended version)
int	draw_particle (PARTICLE_SYSTEM *psys, double xpos, double ypos, int w, int h, double range)
	draw particles on screen
int	free_emitters (PARTICLE_SYSTEM *psys)
	free all emitters in the particle system
int	free_particle_system (PARTICLE_SYSTEM **psys)
	free a particle system
int	init_particle_system (PARTICLE_SYSTEM **psys, int max, double x, double y, double z, int max_sprites)
	initialize a particle system
int	manage_particle (PARTICLE_SYSTEM *psys)
	manage particles using internal timer
int	manage_particle_ex (PARTICLE_SYSTEM *psys, double delta_t)
	manage particles with custom delta time
int	move_particles (PARTICLE_SYSTEM *psys, double vx, double vy, double vz)
	move all particles by a velocity offset
int	remove_emitter (PARTICLE_SYSTEM *psys, const PARTICLE_EMITTER *em)
	remove an emitter from the particle system and free it

Detailed Description

---

Data Structure Documentation

PARTICLE

struct PARTICLE

Structure of a single particle.

Definition at line 74 of file n_particles.h.

Collaboration diagram for PARTICLE:

Data Fields
int	additive	1=additive blend, 0=normal alpha
int	age	current age in msecs (incremented by manage_particle_ex)
ALLEGRO_COLOR	color	color of the particle
ALLEGRO_COLOR	color_end	end color for lerp
ALLEGRO_COLOR	color_start	start color for lerp (set by emitter, ignored if color_start == color_end)
int	depth_sort	1=depth-sorted with terrain, 0=flat overlay after iso pass
struct PARTICLE_EMITTER *	emitter	back-pointer to owning emitter (NULL if spawned manually)
int	lifetime	lifetime (counts down, msecs)
int	lifetime_max	original lifetime at birth (needed for lerp ratio = age/lifetime_max)
int	mode	particle mode: NORMAL_PART,SINUS_PART,PIXEL_PART
PHYSICS	object	particle physical properties
int	size	current size of particle
int	size_end	particle size at death
int	size_start	particle size at birth
int	spr_id	sprite id in library

PARTICLE_EMITTER

struct PARTICLE_EMITTER

Structure of a particle emitter.

Definition at line 112 of file n_particles.h.

Collaboration diagram for PARTICLE_EMITTER:

Data Fields
VECTOR3D	acceleration	constant acceleration (gravity etc.)
int	active	1=emitting, 0=paused
int	additive_blend	1=additive blend, 0=normal alpha blend
int	attached_entity_id	-1=not attached, >=0=entity id
int	burst_count	if >0, emit this many instantly then deactivate
ALLEGRO_COLOR	color_end	particle end color (lerp over lifetime)
ALLEGRO_COLOR	color_start	particle start color
int	depth_sort	1=depth-sorted with terrain, 0=flat overlay
double	emit_accumulator	internal: fractional particle accumulator
double	emit_rate	particles per second (continuous mode)
int	lifetime_max	particle lifetime range max (msecs)
int	lifetime_min	particle lifetime range min (msecs)
int	live_count	current live particle count for this emitter (managed by system)
int	max_particles	per-emitter particle cap (0=unlimited)
VECTOR3D	offset	offset when attached to entity
int	particle_mode	particle draw mode (NORMAL_PART, CIRCLE_PART, PIXEL_PART, FIRE_PART, etc.)
VECTOR3D	position	emitter world position
int	shape	emission shape: 0=point, 1=line, 2=rect, 3=circle
double	shape_h	shape dimension 2: rect height (world units)
double	shape_rotation	shape rotation in radians
double	shape_w	shape dimension 1: line length, rect width, or circle radius (world units)
int	size_end	particle size at death
int	size_start	particle size at birth
int	spr_id	sprite id or -1
VECTOR3D	velocity_max	random velocity range max
VECTOR3D	velocity_min	random velocity range min

PARTICLE_SYSTEM

struct PARTICLE_SYSTEM

Structure of a particle system.

Examples

ex_gui_particles.c.

Definition at line 168 of file n_particles.h.

Collaboration diagram for PARTICLE_SYSTEM:

Data Fields
LIST *	emitters	list of PARTICLE_EMITTER pointers
LIST *	list	list of PARTICLE pointers
int	max_sprites	size of the picture library
VECTOR3D	source	Coordinate of emitting point (used by add_particle/add_particle_ex)
ALLEGRO_BITMAP **	sprites	Library of picture for the particles.
N_TIME	timer	Internal: particle system timer.

Macro Definition Documentation

BITMAP_PART

#define BITMAP_PART   8

bitmap particle

Definition at line 69 of file n_particles.h.

CIRCLE_PART

#define CIRCLE_PART   6

circle particle

Definition at line 65 of file n_particles.h.

FIRE_PART

#define FIRE_PART   4

fire particle

Definition at line 61 of file n_particles.h.

NORMAL_PART

#define NORMAL_PART   0

classic moving particle

Definition at line 53 of file n_particles.h.

PIXEL_PART

#define PIXEL_PART   7

pixel particle

Examples

ex_gui_particles.c.

Definition at line 67 of file n_particles.h.

SINUS_PART

#define SINUS_PART   1

sinus based moving particle

Definition at line 55 of file n_particles.h.

SNOW_PART

#define SNOW_PART   3

snow particle

Definition at line 59 of file n_particles.h.

STAR_PART

#define STAR_PART   5

star particle

Definition at line 63 of file n_particles.h.

TEXT_PART

#define TEXT_PART   9

bitmap particle

Definition at line 71 of file n_particles.h.

TRANS_PART

#define TRANS_PART   2

transparent particle

Definition at line 57 of file n_particles.h.

Function Documentation

add_emitter()

PARTICLE_EMITTER * add_emitter

(

PARTICLE_SYSTEM *

psys

)

add a new emitter to the particle system.

Returns pointer for caller to configure, or NULL on error.

add a new emitter to the particle system.

Parameters

psys	the targeted particle system

Returns

pointer to the new emitter for caller to configure, or NULL on error

Definition at line 503 of file n_particles.c.

References __n_assert, PARTICLE_EMITTER::attached_entity_id, PARTICLE_EMITTER::depth_sort, PARTICLE_SYSTEM::emitters, Free, list_push(), Malloc, and PARTICLE_EMITTER::spr_id.

Here is the call graph for this function:

add_particle()

int add_particle	(	PARTICLE_SYSTEM *	psys,
		int	spr,
		int	mode,
		int	lifetime,
		int	size,
		ALLEGRO_COLOR	color,
		PHYSICS	object
	)

add a particle to the system

add a particle to the system

Parameters

psys	targeted particle system
spr	sprite id of the particle, if any. Set to negative if there is no sprite for the particle
mode	particle mode, NORMAL_PART:if sprite id then use sprite, else draw a pixel,SINUS_PART: snow moving effect,PIXEL_PART: rectfill with size
lifetime	duration of the particle in msecs
size	size of the particle, in pixels
color	color of the particle
object	PHYSICS object in which you set the particle initial position, speed, acceleration, rotation

Returns

TRUE or FALSE

Definition at line 78 of file n_particles.c.

References __n_assert, PARTICLE::age, PARTICLE::color, PARTICLE::color_end, PARTICLE::color_start, PARTICLE::depth_sort, PARTICLE::lifetime, PARTICLE::lifetime_max, PARTICLE_SYSTEM::list, list_push(), Malloc, mode, PARTICLE::mode, LIST::nb_items, LIST::nb_max_items, PARTICLE::object, PARTICLE::size, PARTICLE::size_end, PARTICLE::size_start, PARTICLE_SYSTEM::source, and PARTICLE::spr_id.

Referenced by add_particle_ex(), and main().

Here is the call graph for this function:

Here is the caller graph for this function:

add_particle_at()

int add_particle_at	(	PARTICLE_SYSTEM *	psys,
		int	spr,
		int	mode,
		double	px,
		double	py,
		double	pz,
		int	lifetime,
		int	size_start,
		int	size_end,
		ALLEGRO_COLOR	color_start,
		ALLEGRO_COLOR	color_end,
		double	vx,
		double	vy,
		double	vz,
		double	ax,
		double	ay,
		double	az
	)

add a particle at an absolute world position (not relative to psys->source)

Parameters

psys	targeted particle system
spr	sprite id (-1 for none)
mode	particle draw mode
px	absolute x position
py	absolute y position
pz	absolute z position
lifetime	duration in msecs
size_start	particle size at birth
size_end	particle size at death
color_start	particle start color
color_end	particle end color (lerped over lifetime)
vx	x velocity
vy	y velocity
vz	z velocity
ax	x acceleration
ay	y acceleration
az	z acceleration

Returns

TRUE or FALSE

Definition at line 594 of file n_particles.c.

References __n_assert, PHYSICS::acceleration, PARTICLE::age, PHYSICS::angular_acceleration, PHYSICS::angular_speed, PARTICLE::color, PARTICLE::color_end, PARTICLE::color_start, PARTICLE::depth_sort, PARTICLE::lifetime, PARTICLE::lifetime_max, PARTICLE_SYSTEM::list, list_push(), Malloc, mode, PARTICLE::mode, LIST::nb_items, LIST::nb_max_items, PARTICLE::object, PHYSICS::orientation, PHYSICS::position, PARTICLE::size, PARTICLE::size_end, PARTICLE::size_start, PHYSICS::speed, PARTICLE::spr_id, and VECTOR3D_SET.

Referenced by manage_particle_ex().

Here is the call graph for this function:

Here is the caller graph for this function:

add_particle_ex()

int add_particle_ex	(	PARTICLE_SYSTEM *	psys,
		int	spr,
		int	mode,
		int	off_x,
		int	off_y,
		int	lifetime,
		int	size,
		ALLEGRO_COLOR	color,
		double	vx,
		double	vy,
		double	vz,
		double	ax,
		double	ay,
		double	az
	)

add a particle to the system (extended version)

add a particle to the system (extended version)

Parameters

psys	targeted particle system
spr	sprite id of the particle, if any. Set to negative if there is no sprite for the particle
mode	particle mode, NORMAL_PART:if sprite id then use sprite, else draw a pixel,SINUS_PART: snow moving effect,PIXEL_PART: rectfill with size
off_x	x offset from particle source x position
off_y	y offset from particle source y position
lifetime	duration of the particle in msecs
size	size of the particle, in pixels
color	color of the particle
vx	x speed of the particle
vy	vy speed of the particle
vz	z speed of the particle
ax	x acceleration of the particle
ay	y acceleration of the particle
az	z acceleration of the particle

Returns

TRUE or FALSE

Definition at line 133 of file n_particles.c.

References add_particle(), mode, and VECTOR3D_SET.

Here is the call graph for this function:

draw_particle()

int draw_particle	(	PARTICLE_SYSTEM *	psys,
		double	xpos,
		double	ypos,
		int	w,
		int	h,
		double	range
	)

draw particles on screen

draw particles on screen

Parameters

psys	the targeted particle system
xpos	camera x position
ypos	camera y position
w	width of the current display
h	height of the current display
range	display border tolerance, if( ( x < -range ) || ( x > ( w + range ) ) || ( y< -range ) || ( y > ( h + range ) ) ) next ;

Returns

TRUE or FALSE

Definition at line 385 of file n_particles.c.

References __n_assert, PARTICLE::color, PARTICLE_SYSTEM::list, M_PI, PARTICLE_SYSTEM::max_sprites, PARTICLE::mode, LIST_NODE::next, NORMAL_PART, PARTICLE::object, PHYSICS::orientation, PIXEL_PART, PHYSICS::position, LIST_NODE::ptr, SINUS_PART, PARTICLE::size, PHYSICS::speed, PARTICLE::spr_id, PARTICLE_SYSTEM::sprites, and LIST::start.

Referenced by main().

Here is the caller graph for this function:

free_emitters()

int free_emitters

(

PARTICLE_SYSTEM *

psys

)

free all emitters in the particle system

Parameters

psys	the targeted particle system

Returns

TRUE or FALSE

Definition at line 562 of file n_particles.c.

References __n_assert, PARTICLE_SYSTEM::emitters, Free, remove_list_node, and LIST::start.

Referenced by free_particle_system().

Here is the caller graph for this function:

free_particle_system()

int free_particle_system

(

PARTICLE_SYSTEM **

psys

)

free a particle system

free a particle system

Parameters

psys	a pointer to the particle system to destroy

Returns

TRUE or FALSE

Definition at line 456 of file n_particles.c.

References __n_assert, Free, free_emitters(), FreeNoLog, list_destroy(), and remove_list_node.

Here is the call graph for this function:

init_particle_system()

int init_particle_system	(	PARTICLE_SYSTEM **	psys,
		int	max,
		double	x,
		double	y,
		double	z,
		int	max_sprites
	)

initialize a particle system

Parameters

psys	a pointer to a NULL initialized PARTICLE_SYSTEM pointer
max	maximum number of particles in the system. Set to zero or negative to disable the limitation
x	x position of the emitter
y	y position of the emitter
z	z position of the emitter
max_sprites	maximum number of sprites used in the system. Value from UNLIMITED_LIST_ITEMS (0) to MAX_LIST_ITEMS (SIZE_MAX).

Returns

TRUE or FALSE

Definition at line 40 of file n_particles.c.

References __n_assert, LOG_ERR, Malloc, n_log, new_generic_list(), start_HiTimer(), and UNLIMITED_LIST_ITEMS.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

manage_particle()

int manage_particle

(

PARTICLE_SYSTEM *

psys

)

manage particles using internal timer

manage particles using internal timer

Parameters

psys	the targeted particle system

Returns

TRUE or FALSE

Definition at line 368 of file n_particles.c.

References __n_assert, get_usec(), manage_particle_ex(), and PARTICLE_SYSTEM::timer.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

manage_particle_ex()

int manage_particle_ex	(	PARTICLE_SYSTEM *	psys,
		double	delta_t
	)

manage particles with custom delta time

manage particles with custom delta time

Parameters

psys	the targeted particle system
delta_t	delta time to use, in microseconds

Returns

TRUE or FALSE

Definition at line 241 of file n_particles.c.

References __n_assert, _color_lerp(), _emitter_shape_offset(), _particle_rand_range(), _particle_rand_range_i(), PARTICLE_EMITTER::acceleration, PARTICLE_EMITTER::active, add_particle_at(), PARTICLE::additive, PARTICLE_EMITTER::additive_blend, PARTICLE::age, PARTICLE_EMITTER::burst_count, PARTICLE::color, PARTICLE::color_end, PARTICLE_EMITTER::color_end, PARTICLE::color_start, PARTICLE_EMITTER::color_start, PARTICLE::depth_sort, PARTICLE_EMITTER::depth_sort, PARTICLE_EMITTER::emit_accumulator, PARTICLE_EMITTER::emit_rate, PARTICLE::emitter, PARTICLE_SYSTEM::emitters, LIST::end, Free, PARTICLE::lifetime, PARTICLE::lifetime_max, PARTICLE_EMITTER::lifetime_max, PARTICLE_EMITTER::lifetime_min, PARTICLE_SYSTEM::list, PARTICLE_EMITTER::live_count, PARTICLE_EMITTER::max_particles, LIST_NODE::next, PARTICLE::object, PARTICLE_EMITTER::particle_mode, PARTICLE_EMITTER::position, LIST_NODE::ptr, remove_list_node, PARTICLE::size, PARTICLE::size_end, PARTICLE_EMITTER::size_end, PARTICLE::size_start, PARTICLE_EMITTER::size_start, PARTICLE_EMITTER::spr_id, LIST::start, update_physics_position(), PARTICLE_EMITTER::velocity_max, and PARTICLE_EMITTER::velocity_min.

Referenced by manage_particle().

Here is the call graph for this function:

Here is the caller graph for this function:

move_particles()

int move_particles	(	PARTICLE_SYSTEM *	psys,
		double	vx,
		double	vy,
		double	vz
	)

move all particles by a velocity offset

move all particles by a velocity offset

Parameters

psys	the targeted particle system
vx	x move
vy	y move
vz	z move

Returns

TRUE or FALSE

Definition at line 480 of file n_particles.c.

References __n_assert, PARTICLE_SYSTEM::list, LIST_NODE::next, PARTICLE::object, PHYSICS::position, LIST_NODE::ptr, and LIST::start.

remove_emitter()

int remove_emitter	(	PARTICLE_SYSTEM *	psys,
		const PARTICLE_EMITTER *	em
	)

remove an emitter from the particle system and free it

Parameters

psys	the targeted particle system
em	the emitter to remove

Returns

TRUE or FALSE

Definition at line 530 of file n_particles.c.

References __n_assert, PARTICLE::emitter, PARTICLE_SYSTEM::emitters, Free, PARTICLE_SYSTEM::list, LIST_NODE::next, LIST_NODE::ptr, remove_list_node, and LIST::start.