PythonFireFx


method shader_fire_effect:
Create a fire effect on your game display, surface or sprite texture
shader_fire_effect(surface, width_, height_, factor_, palette_, fire_) -> Surface

Optional arguments
reduce_factor_ = 3,
fire_intensity_ = 32,
smooth_ = True,
bloom_ = True,
fast_bloom_ = True,
bpf_threshold_ = 0,
low_ = 0,
high_ = 600,
brightness_ = True,
brightness_intensity_ = 0.15,
surface_ = None,
adjust_palette_ = False,
hsl_ = (10, 80, 1.8),
transpose_ = False,
border_ = False,
blur_ = True

FIRE SHADER EFFECT OPTIONS

  • FIRE TEXTURE SIZES

input width_ : integer,
input height_ : integer

width_ and height_ values define the size of the texture e.g Surface(width x height)

  • FIRE ASPECT (CONTROL OVER THE WIDTH):

inputs low_ : integer
input high_ : integer

Optional arguments low_ & high_ (integer values) define the width ‘s limits of the fire effect. low_ for the starting point and high_ for the ending of the effect. e.g low_ = 10 and high_ = 200. The fire effect will be contain within width = 10 and 200 low_ & high_ values must be in range [0 … width_]

  • FIRE HEIGHT:

input factor_ : float

The fire maximum height can be adjust with the variable factor_ (float value) value > 3.95 will contain the effect within the display value < 3.95 will enlarge the effect over the display height Recommended value is 3.95 with reduce_factor_ = 3 otherwise adjust the value manually to contain the fire effect within the display

  • SPEED CONSIDERATION

input reduce_factor_ : integer

The argument reduce_factor_ control the size of the texture to be processed e.g : a value of 2, divide by 4 the pygame surface define by the values (width_ & height_) Smaller texture improve the overall performances but will slightly degrade the fire aspect, especially if the blur and smooth option are not enabled. Recommended value for reduce_factor_ is 3 (fast process) reduce_factor_ values must be an integer in range [ 0 … 4] The reduce_factor_ value will have a significant impact on the fire effect maximum height, adjust the argument factor_ accordingly

  • FIRE INTENSITY AT THE SOURCE

input fire_intensity_: integer

Set the fire intensity with the variable fire_intensity_, 0 low flame, 32 maximum flame effect Values must be an int in range [0 … 32]

  • SMOOTHING THE EFFECT

input smooth_: True | False

When smooth_ is True the algorithm will use the pygame function smoothscale (bi-linear filtering) or False the final texture will be adjust with the scale function. Set this variable to False if you need the best performance for the effect or if you require a pixelated fire effect. Otherwise set the variable to True for a more realistic effect.

  • BLOOM EFFECT

input bloom_ : True | False
input fast_bloom_ : True | False
input bpf_threshold_ : integer

Fire effect produce a bright and smooth light effect to the background texture where the fire intensity is at its maximum. Use the flag fast_bloom_ for a compromise between a realistic effect and the best performances The flag fast_bloom_ define a very fast bloom algo using only the smallest texture to create a bloom effect (all the intermediate textures will be bypassed). See the bloom effect project for more details. When fast_bloom is False, all the sub-surfaces will be blit to the final effect and will produce a more realistic fire effect (this will slightly degrade the overall performances). If the fire effect is too bright, you can always adjust the bright pass filter value bpf_threshold_`(this will adjust the bloom intensity) `bpf_threshold_ value must be in range [ 0 … 255] Below 128 the bloom effect will be more noticeable and above 128 only the brightest area will be enhanced.

  • LIGHT EFFECT INTENSITY

input brightness_ : True | False
input brightness_intensity_ : float

When the flag is set to True, the algorithm will use an external function, <shader_brightness24_exclude_inplace_c> to increase the brightness of the effect/texture. A custom color can be passed to the function defining the pixels to be ignored during the process (default is black color). the value must be in range [-1.0 … 1.0]. Values below zero will decrease the brightness of the flame effect and positive values will increase the brightness of the effect (causing bright white patches on the fire texture). Values below -0.4 will cause the fire effect to be translucent and this effect can also be used for simulating ascending heat convection effects on a background texture.

  • OPTIONAL SURFACE

input surface_ : pygame.Surface

This is an optional surface that can be passed to the shader to improve the performances and to avoid a new surface to be generated every iterations. The surface size must match exactly the reduce texture dimensions otherwise an exception will be raise. see reduce_factor_ option to determine the fire texture size that will be processed.

  • COLOR PALETTE ADJUSTMENT

input adjust_palette_ : True | False
input `hsl_` : (10, 80, 1.8)

Set this flag to True to modify the color palette of the fire texture. This allow the HSL color model to be apply to the palette values You can redefine the palette when the flag is True and by customizing a tuple of 3 float values, default is (10, 80, 1.8). The first value control the palette hue value, the second is for the saturation and last, the palette color lightness. With the variable hsl_ you can rotate the palette colors and define a new flame aspect/color/intensity If adjust_palette_ is True the original palette define by the argument palette_, will be disregarded.Instead a new palette will be created with the hsl values

  • FLAME ORIENTATION / DIRECTION & BORDER FLAME EFFECT

input transpose_ = True | False,
input border_ = True | False,

transpose_ = True, this will transpose the final array for e.g If the final fire texture is (w, h) after setting the transpose flag, the final fire texture will become (h, w). As a result the fire effect will be transversal (starting from the right of the display to the left side). You can always transpose/flip the texture to get the right flame orientation

  • BORDER FLAME EFFECT

border_ = True | False,

border_ = True to create a flame effect burning the edge of the display. This version is only compatible with symmetrical display or textures (same width & height). If the display is asymmetric, the final border fire effect will be shown within the display and not neccessary on the frame border

  • FINAL TOUCH

input blur_ : True | False

This will will blur the fire effect for a more realistic appearance, remove all the jagged edge when and pixelated effect

——————————————————————————————

width_ : integer
Size (width) of the surface or display in pixels

height_ : integer
size (height) of the surface or display in pixels

factor_ : float
Value controlling the fire height value
must be in range [3.95 … 4.2].
The value 3.95 gives the highest flame effect

palette_ : numpy.ndarray
buffer containing mapped RGB colors (uint values)

fire_ : numpy.ndarray
shape (w, h) containing float values (fire intensity).
For better performance it is advised to set the array to the size
of the texture after applying the reduction_factor_.
For example if the reduction_factor_ is 2, the texture would have
width >> 1 and height >> 1 and the fire_array should be set to
numpy.empty((height >> 1, width >> 1), float32)

reduce_factor_ : unsigned short int
Can be either 0, 1, 2, 3, 4.
2 and 3 provide the best performance and the best looking effect.

fire_intensity_ : Integer;
Control the original amount of energy at the
bottom of the fire, must be in range of [0 … 32].
32 being the maximum value and the maximum fire intensity

smooth_ : boolean;
True smoothscale (bi-linear filtering) or
scale algorithm jagged edges (mush faster)

bloom_ : boolean;
True or False, True apply a bloom effect to the fire effect

fast_bloom_ : boolean;
Fastest bloom. This reduce the amount of calculation

bpf_threshold_ : integer;
control the bright pass filter threshold
value, must be in range [0 … 255].
Maximum brightness amplification with threshold = 0,
when bpf_threshold_ = 255, no change.

low_ : integer;
Starting position x for the fire effect

high_ : integer;
Ending position x for the fire effect

brightness_ : boolean;
True apply a bright filter shader to the array.
Increase overall brightness of the effect

brightness_intensity_ : float;
must be in range [-1.0 … 1.0] control
the brightness intensity of the effect

surface_ : pygame.Surface.
Pass a surface to the shader for
better performance, otherwise a new surface will be created each
calls.

adjust_palette_ : boolean;
True adjust the palette setting HSL
(hue, saturation, luminescence).
Be aware that if adjust_palette is True, the optional palette
passed to the Shader will be disregarded

hsl_ : tuple;
float values of hue, saturation and luminescence.
Hue in range [0.0 … 100], saturation [0…100],
luminescence [0.0 … 2.0]

transpose_ : boolean;
Transpose the array (w, h) become (h, w).
The fire effect will start from the left and move to the right

border_ : boolean;
Flame effect affect the border of the texture

blur_ : boolean;
Blur the fire effect

return :
Return a pygame surface that can be blit directly to the game display