Mirrors/phaser
2
0
Fork 0
mirror of https://github.com/photonstorm/phaser synced 2024-11-23 13:13:43 +00:00
Code Issues Projects Releases Packages Wiki Activity

Lots more documentation finished

Browse source
This commit is contained in:
Richard Davey 2023-03-21 17:21:45 +00:00
parent f83debe894
commit b89a10c99d
10 changed files with 522 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
src/fx/Bloom.js
View file

@ -10,6 +10,23 @@ var FX_CONST = require('./const');
/**
* @classdesc
* The Bloom FX Controller.
*
* This FX controller manages the bloom effect for a Game Object.
*
* Bloom is an effect used to reproduce an imaging artifact of real-world cameras.
* The effect produces fringes of light extending from the borders of bright areas in an image,
* contributing to the illusion of an extremely bright light overwhelming the
* camera or eye capturing the scene.
*
* A Bloom effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.preFX.addBloom();
* sprite.postFX.addBloom();
* ```
*
* @class Bloom
* @extends Phaser.FX.Controller

17
src/fx/Blur.js
View file

@ -10,6 +10,23 @@ var FX_CONST = require('./const');
/**
* @classdesc
* The Blur FX Controller.
*
* This FX controller manages the blur effect for a Game Object.
*
* A Gaussian blur is the result of blurring an image by a Gaussian function. It is a widely used effect,
* typically to reduce image noise and reduce detail. The visual effect of this blurring technique is a
* smooth blur resembling that of viewing the image through a translucent screen, distinctly different
* from the bokeh effect produced by an out-of-focus lens or the shadow of an object under usual illumination.
*
* A Blur effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.preFX.addBlur();
* sprite.postFX.addBlur();
* ```
*
* @class Blur
* @extends Phaser.FX.Controller

85
src/fx/Bokeh.js
View file

@ -10,6 +10,27 @@ var FX_CONST = require('./const');
/**
* @classdesc
* The Bokeh FX Controller.
*
* This FX controller manages the bokeh effect for a Game Object.
*
* Bokeh refers to a visual effect that mimics the photographic technique of creating a shallow depth of field.
* This effect is used to emphasize the game's main subject or action, by blurring the background or foreground
* elements, resulting in a more immersive and visually appealing experience. It is achieved through rendering
* techniques that simulate the out-of-focus areas, giving a sense of depth and realism to the game's graphics.
*
* This effect can also be used to generate a Tilt Shift effect, which is a technique used to create a miniature
* effect by blurring everything except a small area of the image. This effect is achieved by blurring the
* top and bottom elements, while keeping the center area in focus.
*
* A Bokeh effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.preFX.addBokeh();
* sprite.postFX.addBokeh();
* ```
*
* @class Bokeh
* @extends Phaser.FX.Controller
@ -44,13 +65,77 @@ var Bokeh = new Class({
Controller.call(this, FX_CONST.BOKEH, gameObject);
/**
* The radius of the bokeh effect.
*
* This is a float value, where a radius of 0 will result in no effect being applied,
* and a radius of 1 will result in a strong bokeh. However, you can exceed this value
* for even stronger effects.
*
* @name Phaser.FX.Bokeh#radius
* @type {number}
* @since 3.60.0
*/
this.radius = radius;
/**
* The amount, or strength, of the bokeh effect. Defaults to 1.
*
* @name Phaser.FX.Bokeh#amount
* @type {number}
* @since 3.60.0
*/
this.amount = amount;
/**
* The color contrast, or brightness, of the bokeh effect. Defaults to 0.2.
*
* @name Phaser.FX.Bokeh#contrast
* @type {number}
* @since 3.60.0
*/
this.contrast = contrast;
/**
* Is this a Tilt Shift effect or a standard bokeh effect?
*
* @name Phaser.FX.Bokeh#isTiltShift
* @type {boolean}
* @since 3.60.0
*/
this.isTiltShift = isTiltShift;
/**
* If a Tilt Shift effect this controls the strength of the blur.
*
* Setting this value on a non-Tilt Shift effect will have no effect.
*
* @name Phaser.FX.Bokeh#strength
* @type {number}
* @since 3.60.0
*/
this.strength = strength;
/**
* If a Tilt Shift effect this controls the amount of horizontal blur.
*
* Setting this value on a non-Tilt Shift effect will have no effect.
*
* @name Phaser.FX.Bokeh#blurX
* @type {number}
* @since 3.60.0
*/
this.blurX = blurX;
/**
* If a Tilt Shift effect this controls the amount of vertical blur.
*
* Setting this value on a non-Tilt Shift effect will have no effect.
*
* @name Phaser.FX.Bokeh#blurY
* @type {number}
* @since 3.60.0
*/
this.blurY = blurY;
}

22
src/fx/Circle.js
View file

@ -10,6 +10,26 @@ var FX_CONST = require('./const');
/**
* @classdesc
* The Circle FX Controller.
*
* This FX controller manages the circle effect for a Game Object.
*
* This effect will draw a circle around the texture of the Game Object, effectively masking off
* any area outside of the circle without the need for an actual mask. You can control the thickness
* of the circle, the color of the circle and the color of the background, should the texture be
* transparent. You can also control the feathering applied to the circle, allowing for a harsh or soft edge.
*
* Please note that adding this effect to a Game Object will not change the input area or physics body of
* the Game Object, should it have one.
*
* A Circle effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.preFX.addCircle();
* sprite.postFX.addCircle();
* ```
*
* @class Circle
* @extends Phaser.FX.Controller
@ -19,7 +39,7 @@ var FX_CONST = require('./const');
*
* @param {Phaser.GameObjects.GameObject} gameObject - A reference to the Game Object that has this fx.
* @param {number} [thickness=8] - The width of the circle around the texture, in pixels.
* @param {number} [color=16724914] - The color of the circular ring, given as a number value.
* @param {number} [color=0xfeedb6] - The color of the circular ring, given as a number value.
* @param {number} [backgroundColor=0xff0000] - The color of the background, behind the texture, given as a number value.
* @param {number} [scale=1] - The scale of the circle. The default scale is 1, which is a circle the full size of the underlying texture.
* @param {number} [feather=0.005] - The amount of feathering to apply to the circle from the ring.

3
src/fx/Controller.js
View file

@ -8,6 +8,9 @@ var Class = require('../utils/Class');
/**
* @classdesc
* FX Controller is the base class that all built-in FX use.
*
* You should not normally create an instance of this class directly, but instead use one of the built-in FX that extend it.
*
* @class Controller
* @memberof Phaser.FX

41
src/gameobjects/components/FX.js
View file

@ -452,6 +452,11 @@ var FX = new Class({
/**
* Adds a Blur effect.
*
* A Gaussian blur is the result of blurring an image by a Gaussian function. It is a widely used effect,
* typically to reduce image noise and reduce detail. The visual effect of this blurring technique is a
* smooth blur resembling that of viewing the image through a translucent screen, distinctly different
* from the bokeh effect produced by an out-of-focus lens or the shadow of an object under usual illumination.
*
* @method Phaser.GameObjects.Components.FX#addBlur
* @since 3.60.0
*
@ -494,6 +499,11 @@ var FX = new Class({
/**
* Adds a Bloom effect.
*
* Bloom is an effect used to reproduce an imaging artifact of real-world cameras.
* The effect produces fringes of light extending from the borders of bright areas in an image,
* contributing to the illusion of an extremely bright light overwhelming the
* camera or eye capturing the scene.
*
* @method Phaser.GameObjects.Components.FX#addBloom
* @since 3.60.0
*
@ -527,11 +537,19 @@ var FX = new Class({
/**
* Adds a Circle effect.
*
* This effect will draw a circle around the texture of the Game Object, effectively masking off
* any area outside of the circle without the need for an actual mask. You can control the thickness
* of the circle, the color of the circle and the color of the background, should the texture be
* transparent. You can also control the feathering applied to the circle, allowing for a harsh or soft edge.
*
* Please note that adding this effect to a Game Object will not change the input area or physics body of
* the Game Object, should it have one.
*
* @method Phaser.GameObjects.Components.FX#addCircle
* @since 3.60.0
*
* @param {number} [thickness=8] - The width of the circle around the texture, in pixels.
* @param {number} [color=16724914] - The color of the circular ring, given as a number value.
* @param {number} [color=0xfeedb6] - The color of the circular ring, given as a number value.
* @param {number} [backgroundColor=0xff0000] - The color of the background, behind the texture, given as a number value.
* @param {number} [scale=1] - The scale of the circle. The default scale is 1, which is a circle the full size of the underlying texture.
* @param {number} [feather=0.005] - The amount of feathering to apply to the circle from the ring.
@ -615,6 +633,13 @@ var FX = new Class({
/**
* Adds a Bokeh effect.
*
* Bokeh refers to a visual effect that mimics the photographic technique of creating a shallow depth of field.
* This effect is used to emphasize the game's main subject or action, by blurring the background or foreground
* elements, resulting in a more immersive and visually appealing experience. It is achieved through rendering
* techniques that simulate the out-of-focus areas, giving a sense of depth and realism to the game's graphics.
*
* See also Tilt Shift.
*
* @method Phaser.GameObjects.Components.FX#addBokeh
* @since 3.60.0
*
@ -630,7 +655,13 @@ var FX = new Class({
},
/**
* Adds a TiltShift effect.
* Adds a Tilt Shift effect.
*
* This Bokeh effect can also be used to generate a Tilt Shift effect, which is a technique used to create a miniature
* effect by blurring everything except a small area of the image. This effect is achieved by blurring the
* top and bottom elements, while keeping the center area in focus.
*
* See also Bokeh.
*
* @method Phaser.GameObjects.Components.FX#addTiltShift
* @since 3.60.0
@ -638,9 +669,9 @@ var FX = new Class({
* @param {number} [radius=0.5] - The radius of the bokeh effect.
* @param {number} [amount=1] - The amount of the bokeh effect.
* @param {number} [contrast=0.2] - The color contrast of the bokeh effect.
* @param {number} [blurX=1] - If Tilt Shift, the amount of horizontal blur.
* @param {number} [blurY=1] - If Tilt Shift, the amount of vertical blur.
* @param {number} [strength=1] - If Tilt Shift, the strength of the blur.
* @param {number} [blurX=1] - The amount of horizontal blur.
* @param {number} [blurY=1] - The amount of vertical blur.
* @param {number} [strength=1] - The strength of the blur.
*
* @return {Phaser.FX.Bokeh} The Bokeh TiltShift FX Controller.
*/

80
src/renderer/webgl/pipelines/fx/BloomFXPipeline.js
View file

@ -8,6 +8,31 @@ var Class = require('../../../../utils/Class');
var BloomFrag = require('../../shaders/FXBloom-frag.js');
var PostFXPipeline = require('../PostFXPipeline');
/**
* @classdesc
* The Bloom FX Pipeline.
*
* Bloom is an effect used to reproduce an imaging artifact of real-world cameras.
* The effect produces fringes of light extending from the borders of bright areas in an image,
* contributing to the illusion of an extremely bright light overwhelming the
* camera or eye capturing the scene.
*
* A Bloom effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.postFX.addBloom();
* ```
*
* @class BloomFXPipeline
* @extends Phaser.Renderer.WebGL.WebGLPipeline
* @memberof Phaser.Renderer.WebGL.Pipelines.FX
* @constructor
* @since 3.60.0
*
* @param {Phaser.Game} game - A reference to the Phaser Game instance.
*/
var BloomFXPipeline = new Class({
Extends: PostFXPipeline,
@ -21,11 +46,66 @@ var BloomFXPipeline = new Class({
fragShader: BloomFrag
});
/**
* The number of steps to run the Bloom effect for.
*
* This value should always be an integer.
*
* It defaults to 4. The higher the value, the smoother the Bloom,
* but at the cost of exponentially more gl operations.
*
* Keep this to the lowest possible number you can have it, while
* still looking correct for your game.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BloomFXPipeline#steps
* @type {number}
* @since 3.60.0
*/
this.steps = 4;
/**
* The horizontal offset of the bloom effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BloomFXPipeline#offsetX
* @type {number}
* @since 3.60.0
*/
this.offsetX = 1;
/**
* The vertical offset of the bloom effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BloomFXPipeline#offsetY
* @type {number}
* @since 3.60.0
*/
this.offsetY = 1;
/**
* The strength of the blur process of the bloom effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BloomFXPipeline#blurStrength
* @type {number}
* @since 3.60.0
*/
this.blurStrength = 1;
/**
* The strength of the blend process of the bloom effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BloomFXPipeline#strength
* @type {number}
* @since 3.60.0
*/
this.strength = 1;
/**
* The internal gl color array.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BloomFXPipeline#glcolor
* @type {number[]}
* @since 3.60.0
*/
this.glcolor = [ 1, 1, 1 ];
},

96
src/renderer/webgl/pipelines/fx/BlurFXPipeline.js
View file

@ -10,6 +10,31 @@ var BlurMedFrag = require('../../shaders/FXBlurMed-frag.js');
var BlurHighFrag = require('../../shaders/FXBlurHigh-frag.js');
var PostFXPipeline = require('../PostFXPipeline');
/**
* @classdesc
* The Blur FX Pipeline.
*
* A Gaussian blur is the result of blurring an image by a Gaussian function. It is a widely used effect,
* typically to reduce image noise and reduce detail. The visual effect of this blurring technique is a
* smooth blur resembling that of viewing the image through a translucent screen, distinctly different
* from the bokeh effect produced by an out-of-focus lens or the shadow of an object under usual illumination.
*
* A Blur effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.postFX.addBlur();
* ```
*
* @class BlurFXPipeline
* @extends Phaser.Renderer.WebGL.WebGLPipeline
* @memberof Phaser.Renderer.WebGL.Pipelines.FX
* @constructor
* @since 3.60.0
*
* @param {Phaser.Game} game - A reference to the Phaser Game instance.
*/
var BlurFXPipeline = new Class({
Extends: PostFXPipeline,
@ -38,13 +63,68 @@ var BlurFXPipeline = new Class({
this.activeShader = this.shaders[0];
/**
* The horizontal offset of the blur effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#x
* @type {number}
* @since 3.60.0
*/
this.x = 2;
/**
* The vertical offset of the blur effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#y
* @type {number}
* @since 3.60.0
*/
this.y = 2;
/**
* The number of steps to run the Blur effect for.
*
* This value should always be an integer.
*
* It defaults to 4. The higher the value, the smoother the blur,
* but at the cost of exponentially more gl operations.
*
* Keep this to the lowest possible number you can have it, while
* still looking correct for your game.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#steps
* @type {number}
* @since 3.60.0
*/
this.steps = 4;
/**
* The strength of the blur effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#strength
* @type {number}
* @since 3.60.0
*/
this.strength = 1;
/**
* The internal gl color array.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#glcolor
* @type {number[]}
* @since 3.60.0
*/
this.glcolor = [ 1, 1, 1 ];
},
/**
* Sets the quality of the blur effect to low.
*
* @method Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#setQualityLow
* @since 3.60.0
*
* @return {this} This FX Pipeline.
*/
setQualityLow: function ()
{
this.activeShader = this.shaders[0];
@ -52,6 +132,14 @@ var BlurFXPipeline = new Class({
return this;
},
/**
* Sets the quality of the blur effect to medium.
*
* @method Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#setQualityMedium
* @since 3.60.0
*
* @return {this} This FX Pipeline.
*/
setQualityMedium: function ()
{
this.activeShader = this.shaders[1];
@ -59,6 +147,14 @@ var BlurFXPipeline = new Class({
return this;
},
/**
* Sets the quality of the blur effect to high.
*
* @method Phaser.Renderer.WebGL.Pipelines.FX.BlurFXPipeline#setQualityHigh
* @since 3.60.0
*
* @return {this} This FX Pipeline.
*/
setQualityHigh: function ()
{
this.activeShader = this.shaders[2];

94
src/renderer/webgl/pipelines/fx/BokehFXPipeline.js
View file

@ -8,6 +8,35 @@ var Class = require('../../../../utils/Class');
var BokehFrag = require('../../shaders/FXBokeh-frag.js');
var PostFXPipeline = require('../PostFXPipeline');
/**
* @classdesc
* The Bokeh FX Pipeline.
*
* Bokeh refers to a visual effect that mimics the photographic technique of creating a shallow depth of field.
* This effect is used to emphasize the game's main subject or action, by blurring the background or foreground
* elements, resulting in a more immersive and visually appealing experience. It is achieved through rendering
* techniques that simulate the out-of-focus areas, giving a sense of depth and realism to the game's graphics.
*
* This effect can also be used to generate a Tilt Shift effect, which is a technique used to create a miniature
* effect by blurring everything except a small area of the image. This effect is achieved by blurring the
* top and bottom elements, while keeping the center area in focus.
*
* A Bokeh effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.postFX.addBokeh();
* ```
*
* @class BokehFXPipeline
* @extends Phaser.Renderer.WebGL.WebGLPipeline
* @memberof Phaser.Renderer.WebGL.Pipelines.FX
* @constructor
* @since 3.60.0
*
* @param {Phaser.Game} game - A reference to the Phaser Game instance.
*/
var BokehFXPipeline = new Class({
Extends: PostFXPipeline,
@ -21,12 +50,77 @@ var BokehFXPipeline = new Class({
fragShader: BokehFrag
});
/**
* Is this a Tilt Shift effect or a standard bokeh effect?
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#isTiltShift
* @type {boolean}
* @since 3.60.0
*/
this.isTiltShift = false;
/**
* If a Tilt Shift effect this controls the strength of the blur.
*
* Setting this value on a non-Tilt Shift effect will have no effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#strength
* @type {number}
* @since 3.60.0
*/
this.strength = 1;
/**
* If a Tilt Shift effect this controls the amount of horizontal blur.
*
* Setting this value on a non-Tilt Shift effect will have no effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#blurX
* @type {number}
* @since 3.60.0
*/
this.blurX = 1;
/**
* If a Tilt Shift effect this controls the amount of vertical blur.
*
* Setting this value on a non-Tilt Shift effect will have no effect.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#blurY
* @type {number}
* @since 3.60.0
*/
this.blurY = 1;
/**
* The radius of the bokeh effect.
*
* This is a float value, where a radius of 0 will result in no effect being applied,
* and a radius of 1 will result in a strong bokeh. However, you can exceed this value
* for even stronger effects.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#radius
* @type {number}
* @since 3.60.0
*/
this.radius = 0.5;
/**
* The amount, or strength, of the bokeh effect. Defaults to 1.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#amount
* @type {number}
* @since 3.60.0
*/
this.amount = 1;
/**
* The color contrast, or brightness, of the bokeh effect. Defaults to 0.2.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.BokehFXPipeline#contrast
* @type {number}
* @since 3.60.0
*/
this.contrast = 0.2;
},

74
src/renderer/webgl/pipelines/fx/CircleFXPipeline.js
View file

@ -8,6 +8,34 @@ var Class = require('../../../../utils/Class');
var CircleFrag = require('../../shaders/FXCircle-frag.js');
var PostFXPipeline = require('../PostFXPipeline');
/**
* @classdesc
* The Circle FX Pipeline.
*
* This effect will draw a circle around the texture of the Game Object, effectively masking off
* any area outside of the circle without the need for an actual mask. You can control the thickness
* of the circle, the color of the circle and the color of the background, should the texture be
* transparent. You can also control the feathering applied to the circle, allowing for a harsh or soft edge.
*
* Please note that adding this effect to a Game Object will not change the input area or physics body of
* the Game Object, should it have one.
*
* A Circle effect is added to a Game Object via the FX component:
*
* ```js
* const sprite = this.add.sprite();
*
* sprite.postFX.addCircle();
* ```
*
* @class CircleFXPipeline
* @extends Phaser.Renderer.WebGL.WebGLPipeline
* @memberof Phaser.Renderer.WebGL.Pipelines.FX
* @constructor
* @since 3.60.0
*
* @param {Phaser.Game} game - A reference to the Phaser Game instance.
*/
var CircleFXPipeline = new Class({
Extends: PostFXPipeline,
@ -21,14 +49,58 @@ var CircleFXPipeline = new Class({
fragShader: CircleFrag
});
/**
* The scale of the circle. The default scale is 1, which is a circle
* the full size of the underlying texture. Reduce this value to create
* a smaller circle, or increase it to create a circle that extends off
* the edges of the texture.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.CircleFXPipeline#scale
* @type {number}
* @since 3.60.0
*/
this.scale = 1;
// 0.005 = strength of the ring (0.5 = super soft, 0.05 = gentle, 0.005 = harsh)
/**
* The amount of feathering to apply to the circle from the ring,
* extending into the middle of the circle. The default is 0.005,
* which is a very low amount of feathering just making sure the ring
* has a smooth edge. Increase this amount to a value such as 0.5
* or 0.025 for larger amounts of feathering.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.CircleFXPipeline#feather
* @type {number}
* @since 3.60.0
*/
this.feather = 0.005;
/**
* The width of the circle around the texture, in pixels. This value
* doesn't factor in the feather, which can extend the thickness
* internally depending on its value.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.CircleFXPipeline#thickness
* @type {number}
* @since 3.60.0
*/
this.thickness = 8;
/**
* The internal gl color array for the ring color.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.CircleFXPipeline#glcolor
* @type {number[]}
* @since 3.60.0
*/
this.glcolor = [ 1, 0.2, 0.7 ];
/**
* The internal gl color array for the background color.
*
* @name Phaser.Renderer.WebGL.Pipelines.FX.CircleFXPipeline#glcolor2
* @type {number[]}
* @since 3.60.0
*/
this.glcolor2 = [ 1, 0, 0, 0.4 ];
},