PythonFireFx
¶
- method shader_fire_effect:
Create a fire effect on your game display, surface or sprite textureshader_fire_effect(surface, width_, height_, factor_, palette_, fire_) -> SurfaceOptional argumentsreduce_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_ = TrueFIRE SHADER EFFECT OPTIONS
FIRE TEXTURE SIZES
input width_ : integer,input height_ : integerwidth_ and height_ values define the size of the texture e.g Surface(width x height)
FIRE ASPECT (CONTROL OVER THE WIDTH):
inputs low_ : integerinput high_ : integerOptional 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_ : floatThe 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_ : integerThe 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_: integerSet 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 | FalseWhen 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 | Falseinput fast_bloom_ : True | Falseinput bpf_threshold_ : integerFire 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 | Falseinput brightness_intensity_ : floatWhen 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.SurfaceThis 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 | Falseinput `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 | FalseThis will will blur the fire effect for a more realistic appearance, remove all the jagged edge when and pixelated effect
——————————————————————————————width_ : integerSize (width) of the surface or display in pixelsheight_ : integersize (height) of the surface or display in pixelsfactor_ : floatValue controlling the fire height valuemust be in range [3.95 … 4.2].The value 3.95 gives the highest flame effectpalette_ : numpy.ndarraybuffer containing mapped RGB colors (uint values)fire_ : numpy.ndarrayshape (w, h) containing float values (fire intensity).For better performance it is advised to set the array to the sizeof the texture after applying the reduction_factor_.For example if the reduction_factor_ is 2, the texture would havewidth >> 1 and height >> 1 and the fire_array should be set tonumpy.empty((height >> 1, width >> 1), float32)reduce_factor_ : unsigned short intCan 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 thebottom of the fire, must be in range of [0 … 32].32 being the maximum value and the maximum fire intensitysmooth_ : boolean;True smoothscale (bi-linear filtering) orscale algorithm jagged edges (mush faster)bloom_ : boolean;True or False, True apply a bloom effect to the fire effectfast_bloom_ : boolean;Fastest bloom. This reduce the amount of calculationbpf_threshold_ : integer;control the bright pass filter thresholdvalue, 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 effecthigh_ : integer;Ending position x for the fire effectbrightness_ : boolean;True apply a bright filter shader to the array.Increase overall brightness of the effectbrightness_intensity_ : float;must be in range [-1.0 … 1.0] controlthe brightness intensity of the effectsurface_ : pygame.Surface.Pass a surface to the shader forbetter performance, otherwise a new surface will be created eachcalls.adjust_palette_ : boolean;True adjust the palette setting HSL(hue, saturation, luminescence).Be aware that if adjust_palette is True, the optional palettepassed to the Shader will be disregardedhsl_ : 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 rightborder_ : boolean;Flame effect affect the border of the textureblur_ : boolean;Blur the fire effectreturn :Return a pygame surface that can be blit directly to the game display