JSDoc improvements

This commit is contained in:
Richard Davey 2020-12-14 13:33:42 +00:00
parent e08b5386dd
commit cbe1a3219a
12 changed files with 258 additions and 75 deletions

View file

@ -13,7 +13,6 @@ var Render = require('./PointLightRender');
/**
* @classdesc
*
* TODO
*
* @class PointLight

View file

@ -19,7 +19,6 @@ var RandomXYZW = function (vec4, scale)
{
if (scale === undefined) { scale = 1; }
// TODO: Not spherical; should fix this for more uniform distribution
vec4.x = (Math.random() * 2 - 1) * scale;
vec4.y = (Math.random() * 2 - 1) * scale;
vec4.z = (Math.random() * 2 - 1) * scale;

View file

@ -482,9 +482,6 @@ var Vector4 = new Class({
*/
transformQuat: function (q)
{
// TODO: is this really the same as Vector3?
// Also, what about this: http://molecularmusings.wordpress.com/2013/05/24/a-faster-quaternion-vector-multiplication/
// benchmarks: http://jsperf.com/quaternion-transform-vec3-implementations
var x = this.x;
var y = this.y;
var z = this.z;
@ -527,7 +524,6 @@ var Vector4 = new Class({
});
// TODO: Check if these are required internally, if not, remove.
Vector4.prototype.sub = Vector4.prototype.subtract;
Vector4.prototype.mul = Vector4.prototype.multiply;
Vector4.prototype.div = Vector4.prototype.divide;

View file

@ -15,8 +15,6 @@
* greater than 0 then it's a counter-clockwise rotation, if < 0 then it's
* a clockwise rotation.
*
* TODO: Wrap the angles in this function?
*
* @function Phaser.Math.Angle.ShortestBetween
* @since 3.0.0
*

View file

@ -1565,7 +1565,7 @@ var World = new Class({
overlap /= 2;
}
// TODO this is inadequate for circle-rectangle separation
// Note: This is inadequate for circle-rectangle separation
var angle = AngleBetweenPoints(body1.center, body2.center);
var overlapX = (overlap + MATH_CONST.EPSILON) * Math.cos(angle);

View file

@ -21,18 +21,21 @@ var UtilityPipeline = require('./pipelines/UtilityPipeline');
/**
* @classdesc
* The Pipeline Manager is responsible for the creation, activation, running and destruction
* of WebGL Pipelines in Phaser 3.
* of WebGL Pipelines and Post FX Pipelines in Phaser 3.
*
* The `WebGLRenderer` owns a single instance of the Pipeline Manager, which you can access
* via the `WebGLRenderer.pipelines` property.
*
* By default, there are 5 pipelines installed into the Pipeline Manager when Phaser boots:
* By default, there are 8 pipelines installed into the Pipeline Manager when Phaser boots:
*
* 1. The Multi Pipeline. Responsible for all multi-texture rendering, i.e. Sprites, Shapes.
* 2. The Single Pipeline. Responsible for rendering Game Objects that explicitly require one bound texture.
* 1. The Multi Pipeline. Responsible for all multi-texture rendering, i.e. Sprites and Tilemaps.
* 2. The Graphics Pipeline. Responsible for rendering Graphics and Shape objects.
* 3. The Rope Pipeline. Responsible for rendering the Rope Game Object.
* 4. The Light Pipeline. Responsible for rendering the Light Game Object.
* 5. The Bitmap Mask Pipeline. Responsible for Bitmap Mask rendering.
* 5. The Point Light Pipeline. Responsible for rendering the Point Light Game Object.
* 6. The Single Pipeline. Responsible for rendering Game Objects that explicitly require one bound texture.
* 7. The Bitmap Mask Pipeline. Responsible for Bitmap Mask rendering.
* 8. The Utility Pipeline. Responsible for providing lots of handy texture manipulation functions.
*
* You can add your own custom pipeline via the `PipelineManager.add` method. Pipelines are
* identified by unique string-based keys.
@ -770,9 +773,7 @@ var PipelineManager = new Class({
*/
copyFrame: function (source, target, brightness, clear, clearAlpha)
{
var pipeline = this.setUtility(this.UTILITY_PIPELINE.copyShader);
pipeline.copyFrame(source, target, brightness, clear, clearAlpha);
this.setUtility(this.UTILITY_PIPELINE.copyShader).copyFrame(source, target, brightness, clear, clearAlpha);
return this;
},
@ -794,9 +795,7 @@ var PipelineManager = new Class({
*/
copyToGame: function (source)
{
var pipeline = this.setUtility(this.UTILITY_PIPELINE.copyShader);
pipeline.copyToGame(source);
this.setUtility(this.UTILITY_PIPELINE.copyShader).copyToGame(source);
return this;
},
@ -824,9 +823,7 @@ var PipelineManager = new Class({
*/
drawFrame: function (source, target, clearAlpha, colorMatrix)
{
var pipeline = this.setUtility(this.UTILITY_PIPELINE.colorMatrixShader);
pipeline.drawFrame(source, target, clearAlpha, colorMatrix);
this.setUtility(this.UTILITY_PIPELINE.colorMatrixShader).drawFrame(source, target, clearAlpha, colorMatrix);
return this;
},
@ -850,9 +847,7 @@ var PipelineManager = new Class({
*/
blendFrames: function (source1, source2, target, strength, clearAlpha)
{
var pipeline = this.setUtility(this.UTILITY_PIPELINE.linearShader);
pipeline.blendFrames(source1, source2, target, strength, clearAlpha);
this.setUtility(this.UTILITY_PIPELINE.linearShader).blendFrames(source1, source2, target, strength, clearAlpha);
return this;
},
@ -876,9 +871,7 @@ var PipelineManager = new Class({
*/
blendFramesAdditive: function (source1, source2, target, strength, clearAlpha)
{
var pipeline = this.setUtility(this.UTILITY_PIPELINE.addShader);
pipeline.blendFrames(source1, source2, target, strength, clearAlpha);
this.setUtility(this.UTILITY_PIPELINE.addShader).blendFramesAdditive(source1, source2, target, strength, clearAlpha);
return this;
},
@ -891,6 +884,8 @@ var PipelineManager = new Class({
*
* @param {Phaser.Renderer.WebGL.RenderTarget} target - The Render Target to clear.
* @param {boolean} [clearAlpha=true] - Clear the alpha channel when running `gl.clear` on the target?
*
* @return {this} This Pipeline Manager instance.
*/
clearFrame: function (target, clearAlpha)
{
@ -899,6 +894,64 @@ var PipelineManager = new Class({
return this;
},
/**
* Copy the `source` Render Target to the `target` Render Target.
*
* The difference with this copy is that no resizing takes place. If the `source`
* Render Target is larger than the `target` then only a portion the same size as
* the `target` dimensions is copied across.
*
* You can optionally set the brightness factor of the copy.
*
* @method Phaser.Renderer.WebGL.PipelineManager#blitFrame
* @since 3.50.0
*
* @param {Phaser.Renderer.WebGL.RenderTarget} source - The source Render Target.
* @param {Phaser.Renderer.WebGL.RenderTarget} target - The target Render Target.
* @param {number} [brightness=1] - The brightness value applied to the frame copy.
* @param {boolean} [clear=true] - Clear the target before copying?
* @param {boolean} [clearAlpha=true] - Clear the alpha channel when running `gl.clear` on the target?
* @param {boolean} [eraseMode=false] - Erase source from target using ERASE Blend Mode?
*
* @return {this} This Pipeline Manager instance.
*/
blitFrame: function (source, target, brightness, clear, clearAlpha, eraseMode)
{
this.setUtility(this.UTILITY_PIPELINE.copyShader).blitFrame(source, target, brightness, clear, clearAlpha, eraseMode);
return this;
},
/**
* Binds the `source` Render Target and then copies a section of it to the `target` Render Target.
*
* This method is extremely fast because it uses `gl.copyTexSubImage2D` and doesn't
* require the use of any shaders. Remember the coordinates are given in standard WebGL format,
* where x and y specify the lower-left corner of the section, not the top-left. Also, the
* copy entirely replaces the contents of the target texture, no 'merging' or 'blending' takes
* place.
*
* @method Phaser.Renderer.WebGL.PipelineManager#copyFrameRect
* @since 3.50.0
*
* @param {Phaser.Renderer.WebGL.RenderTarget} source - The source Render Target.
* @param {Phaser.Renderer.WebGL.RenderTarget} target - The target Render Target.
* @param {number} x - The x coordinate of the lower left corner where to start copying.
* @param {number} y - The y coordinate of the lower left corner where to start copying.
* @param {number} width - The width of the texture.
* @param {number} height - The height of the texture.
* @param {boolean} [clear=true] - Clear the target before copying?
* @param {boolean} [clearAlpha=true] - Clear the alpha channel when running `gl.clear` on the target?
*
* @return {this} This Pipeline Manager instance.
*/
copyFrameRect: function (source, target, x, y, width, height, clear, clearAlpha)
{
this.UTILITY_PIPELINE.copyFrameRect(source, target, x, y, width, height, clear, clearAlpha);
return this;
},
/**
* Returns `true` if the current pipeline is forced to use texture unit zero.
*

View file

@ -14,7 +14,6 @@ var WebGLPipeline = require('../WebGLPipeline');
/**
* @classdesc
*
* The Bitmap Mask Pipeline handles all of the bitmap mask rendering in WebGL for applying
* alpha masks to Game Objects. It works by sampling two texture on the fragment shader and
* using the fragments alpha to clip the region.

View file

@ -41,11 +41,8 @@ var tempVec2 = new Vec2();
* `inTintEffect` (float, offset 20)
* `inTint` (vec4, offset 24, normalized)
*
* The default shader uniforms for this pipeline are:
* The default shader uniforms for this pipeline are those from the Multi Pipeline, plus:
*
* `uProjectionMatrix` (mat4)
* `uViewMatrix` (mat4)
* `uModelMatrix` (mat4)
* `uMainSampler` (sampler2D)
* `uNormSampler` (sampler2D)
* `uCamera` (vec4)

View file

@ -10,6 +10,35 @@ var PointLightShaderSourceFS = require('../shaders/PointLight-frag.js');
var PointLightShaderSourceVS = require('../shaders/PointLight-vert.js');
var WebGLPipeline = require('../WebGLPipeline');
/**
* @classdesc
* The Point Light Pipeline handles rendering the Point Light Game Objects in WebGL.
*
* The fragment shader it uses can be found in `shaders/src/BitmapMask.frag`.
* The vertex shader it uses can be found in `shaders/src/BitmapMask.vert`.
*
* The default shader attributes for this pipeline are:
*
* `inPosition` (vec2)
* `inLightPosition` (vec2)
* `inLightRadius` (float)
* `inLightAttenuation` (float)
* `inLightColor` (vec4)
*
* The default shader uniforms for this pipeline are:
*
* `uProjectionMatrix` (mat4)
* `uResolution` (vec2)
* `uCameraZoom` (sampler2D)
*
* @class PointLightPipeline
* @extends Phaser.Renderer.WebGL.WebGLPipeline
* @memberof Phaser.Renderer.WebGL.Pipelines
* @constructor
* @since 3.50.0
*
* @param {Phaser.Types.Renderer.WebGL.WebGLPipelineConfig} config - The configuration options for this pipeline.
*/
var PointLightPipeline = new Class({
Extends: WebGLPipeline,
@ -32,9 +61,6 @@ var PointLightPipeline = new Class({
{
name: 'inLightRadius'
},
{
name: 'inLightFalloff'
},
{
name: 'inLightAttenuation'
},
@ -53,12 +79,30 @@ var PointLightPipeline = new Class({
this.set1f('uCameraZoom', camera.zoom);
},
/**
* Adds a Point Light Game Object to the batch, flushing if required.
*
* @method Phaser.Renderer.WebGL.Pipelines.PointLightPipeline#batchPointLight
* @since 3.50.0
*
* @param {Phaser.GameObjects.PointLight} light - The Point Light Game Object.
* @param {Phaser.Cameras.Scene2D.Camera} camera - The camera rendering the Point Light.
* @param {number} x0 - The top-left x position.
* @param {number} y0 - The top-left y position.
* @param {number} x1 - The bottom-left x position.
* @param {number} y1 - The bottom-left y position.
* @param {number} x2 - The bottom-right x position.
* @param {number} y2 - The bottom-right y position.
* @param {number} x3 - The top-right x position.
* @param {number} y3 - The top-right y position.
* @param {number} lightX - The horizontal center of the light.
* @param {number} lightY - The vertical center of the light.
*/
batchPointLight: function (light, camera, x0, y0, x1, y1, x2, y2, x3, y3, lightX, lightY)
{
var color = light.color;
var intensity = light.intensity;
var radius = light.radius;
var falloff = light.falloff;
var attenuation = light.attenuation;
var r = color.r * intensity;
@ -71,15 +115,35 @@ var PointLightPipeline = new Class({
this.flush();
}
this.batchLightVert(x0, y0, lightX, lightY, radius, falloff, attenuation, r, g, b, a);
this.batchLightVert(x1, y1, lightX, lightY, radius, falloff, attenuation, r, g, b, a);
this.batchLightVert(x2, y2, lightX, lightY, radius, falloff, attenuation, r, g, b, a);
this.batchLightVert(x0, y0, lightX, lightY, radius, falloff, attenuation, r, g, b, a);
this.batchLightVert(x2, y2, lightX, lightY, radius, falloff, attenuation, r, g, b, a);
this.batchLightVert(x3, y3, lightX, lightY, radius, falloff, attenuation, r, g, b, a);
this.batchLightVert(x0, y0, lightX, lightY, radius, attenuation, r, g, b, a);
this.batchLightVert(x1, y1, lightX, lightY, radius, attenuation, r, g, b, a);
this.batchLightVert(x2, y2, lightX, lightY, radius, attenuation, r, g, b, a);
this.batchLightVert(x0, y0, lightX, lightY, radius, attenuation, r, g, b, a);
this.batchLightVert(x2, y2, lightX, lightY, radius, attenuation, r, g, b, a);
this.batchLightVert(x3, y3, lightX, lightY, radius, attenuation, r, g, b, a);
},
batchLightVert: function (x, y, lightX, lightY, radius, falloff, attenuation, r, g, b, a)
/**
* Adds a single Point Light vertex to the current vertex buffer and increments the
* `vertexCount` property by 1.
*
* This method is called directly by `batchPointLight`.
*
* @method Phaser.Renderer.WebGL.Pipelines.PointLightPipeline#batchLightVert
* @since 3.50.0
*
* @param {number} x - The vertex x position.
* @param {number} y - The vertex y position.
* @param {number} lightX - The horizontal center of the light.
* @param {number} lightY - The vertical center of the light.
* @param {number} radius - The radius of the light.
* @param {number} attenuation - The attenuation of the light.
* @param {number} r - The red color channel of the light.
* @param {number} g - The green color channel of the light.
* @param {number} b - The blue color channel of the light.
* @param {number} a - The alpha color channel of the light.
*/
batchLightVert: function (x, y, lightX, lightY, radius, attenuation, r, g, b, a)
{
var vertexViewF32 = this.vertexViewF32;
@ -90,7 +154,6 @@ var PointLightPipeline = new Class({
vertexViewF32[++vertexOffset] = lightX;
vertexViewF32[++vertexOffset] = lightY;
vertexViewF32[++vertexOffset] = radius;
vertexViewF32[++vertexOffset] = falloff;
vertexViewF32[++vertexOffset] = attenuation;
vertexViewF32[++vertexOffset] = r;
vertexViewF32[++vertexOffset] = g;

View file

@ -13,20 +13,29 @@ var WebGLPipeline = require('../WebGLPipeline');
/**
* @classdesc
* TODO
* The Post FX Pipeline is a special kind of pipeline specifically for handling post
* processing effects. Where-as a standard Pipeline allows you to control the process
* of rendering Game Objects by configuring the shaders and attributes used to draw them,
* a Post FX Pipeline is designed to allow you to apply processing _after_ the Game Object/s
* have been rendered. Typical examples of post processing effects are bloom filters,
* blurs, light effects and color manipulation.
*
* The fragment shader it uses can be found in `shaders/src/PostFX.frag`.
* The vertex shader it uses can be found in `shaders/src/PostFX.vert`.
* The pipeline works by creating a tiny vertex buffer with just one single hard-coded quad
* in it. Game Objects can have a Post Pipeline set on them. Those objects are then rendered
* using their standard pipeline, but are redirected to the Render Targets owned by the
* post pipeline, which can then apply their own shaders and effects, before passing them
* back to the main renderer.
*
* Please see the Phaser 3 examples for further details on this extensive subject.
*
* The default fragment shader it uses can be found in `shaders/src/PostFX.frag`.
* The default vertex shader it uses can be found in `shaders/src/Quad.vert`.
*
* The default shader attributes for this pipeline are:
*
* `inPosition` (vec2, offset 0)
* `inTexCoord` (vec2, offset 8)
*
* The default shader uniforms for this pipeline are:
*
* `uMainSampler` (sampler2D)
*
* @class PostFXPipeline
* @extends Phaser.Renderer.WebGL.WebGLPipeline
* @memberof Phaser.Renderer.WebGL.Pipelines
@ -333,6 +342,70 @@ var PostFXPipeline = new Class({
this.manager.blendFramesAdditive(source1, source2, target, strength, clearAlpha);
},
/**
* Clears the given Render Target.
*
* @method Phaser.Renderer.WebGL.Pipelines.PostFXPipeline#clearFrame
* @since 3.50.0
*
* @param {Phaser.Renderer.WebGL.RenderTarget} target - The Render Target to clear.
* @param {boolean} [clearAlpha=true] - Clear the alpha channel when running `gl.clear` on the target?
*/
clearFrame: function (target, clearAlpha)
{
this.manager.clearFrame(target, clearAlpha);
},
/**
* Copy the `source` Render Target to the `target` Render Target.
*
* The difference with this copy is that no resizing takes place. If the `source`
* Render Target is larger than the `target` then only a portion the same size as
* the `target` dimensions is copied across.
*
* You can optionally set the brightness factor of the copy.
*
* @method Phaser.Renderer.WebGL.Pipelines.PostFXPipeline#blitFrame
* @since 3.50.0
*
* @param {Phaser.Renderer.WebGL.RenderTarget} source - The source Render Target.
* @param {Phaser.Renderer.WebGL.RenderTarget} target - The target Render Target.
* @param {number} [brightness=1] - The brightness value applied to the frame copy.
* @param {boolean} [clear=true] - Clear the target before copying?
* @param {boolean} [clearAlpha=true] - Clear the alpha channel when running `gl.clear` on the target?
* @param {boolean} [eraseMode=false] - Erase source from target using ERASE Blend Mode?
*/
blitFrame: function (source, target, brightness, clear, clearAlpha, eraseMode)
{
this.manager.blitFrame(source, target, brightness, clear, clearAlpha, eraseMode);
},
/**
* Binds the `source` Render Target and then copies a section of it to the `target` Render Target.
*
* This method is extremely fast because it uses `gl.copyTexSubImage2D` and doesn't
* require the use of any shaders. Remember the coordinates are given in standard WebGL format,
* where x and y specify the lower-left corner of the section, not the top-left. Also, the
* copy entirely replaces the contents of the target texture, no 'merging' or 'blending' takes
* place.
*
* @method Phaser.Renderer.WebGL.Pipelines.PostFXPipeline#copyFrameRect
* @since 3.50.0
*
* @param {Phaser.Renderer.WebGL.RenderTarget} source - The source Render Target.
* @param {Phaser.Renderer.WebGL.RenderTarget} target - The target Render Target.
* @param {number} x - The x coordinate of the lower left corner where to start copying.
* @param {number} y - The y coordinate of the lower left corner where to start copying.
* @param {number} width - The width of the texture.
* @param {number} height - The height of the texture.
* @param {boolean} [clear=true] - Clear the target before copying?
* @param {boolean} [clearAlpha=true] - Clear the alpha channel when running `gl.clear` on the target?
*/
copyFrameRect: function (source, target, x, y, width, height, clear, clearAlpha)
{
this.manager.copyFrameRect(source, target, x, y, width, height, clear, clearAlpha);
},
/**
* Binds this pipeline and draws the `source` Render Target to the `target` Render Target.
*

View file

@ -10,7 +10,6 @@ var MultiPipeline = require('./MultiPipeline');
/**
* @classdesc
*
* The Rope Pipeline is a variation of the Multi Pipeline that uses a `TRIANGLE_STRIP` for
* its topology, instead of TRIANGLES. This is primarily used by the Rope Game Object,
* or anything that extends it.
@ -31,8 +30,6 @@ var MultiPipeline = require('./MultiPipeline');
* The default shader uniforms for this pipeline are:
*
* `uProjectionMatrix` (mat4)
* `uViewMatrix` (mat4)
* `uModelMatrix` (mat4)
* `uMainSampler` (sampler2D array)
*
* The pipeline is structurally identical to the Multi Pipeline and should be treated as such.

View file

@ -26,14 +26,13 @@ var WebGLPipeline = require('../WebGLPipeline');
* 3) Linear Blend Mode Shader. Blends two textures using a linear blend mode.
* 4) Color Matrix Copy Shader. Draws a texture to a target using a Color Matrix.
*
* You typically do not extend or access this pipeline directly, but instead go
* via the following methods in the Pipeline Manager:
* You do not extend this pipeline, but instead get a reference to it from the Pipeline
* Manager via the `setUtility` method. You can also access methods such as `copyFrame`
* directly from the Pipeline Manager.
*
* `copyFrame`
* `copyFrameRect`
* `drawFrame`
* `blendFrames`
* `blendFramesAdditive`
* This pipeline provides methods for manipulating framebuffer backed textures, such as
* copying or blending one texture to another, copying a portion of a texture, additively
* blending two textures, flipping textures and more.
*
* The default shader attributes for this pipeline are:
*
@ -333,8 +332,10 @@ var UtilityPipeline = new Class({
var gl = this.gl;
this.set1i('uMainSampler', 0, this.copyShader);
this.set1f('uBrightness', brightness, this.copyShader);
this.setShader(this.copyShader);
this.set1i('uMainSampler', 0);
this.set1f('uBrightness', brightness);
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, source.texture);
@ -399,8 +400,10 @@ var UtilityPipeline = new Class({
var gl = this.gl;
this.set1i('uMainSampler', 0, this.copyShader);
this.set1f('uBrightness', brightness, this.copyShader);
this.setShader(this.copyShader);
this.set1i('uMainSampler', 0);
this.set1f('uBrightness', brightness);
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, source.texture);
@ -529,8 +532,10 @@ var UtilityPipeline = new Class({
{
var gl = this.gl;
this.set1i('uMainSampler', 0, this.copyShader);
this.set1f('uBrightness', 1, this.copyShader);
this.setShader(this.copyShader);
this.set1i('uMainSampler', 0);
this.set1f('uBrightness', 1);
this.renderer.popFramebuffer();
@ -567,9 +572,11 @@ var UtilityPipeline = new Class({
var gl = this.gl;
this.set1i('uMainSampler', 0, this.colorMatrixShader);
this.set1fv('uColorMatrix', colorMatrix.getData(), this.colorMatrixShader);
this.set1f('uAlpha', colorMatrix.alpha, this.colorMatrixShader);
this.setShader(this.colorMatrixShader);
this.set1i('uMainSampler', 0);
this.set1fv('uColorMatrix', colorMatrix.getData());
this.set1f('uAlpha', colorMatrix.alpha);
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, source.texture);
@ -625,9 +632,11 @@ var UtilityPipeline = new Class({
var gl = this.gl;
this.set1i('uMainSampler1', 0, blendShader);
this.set1i('uMainSampler2', 1, blendShader);
this.set1f('uStrength', strength, blendShader);
this.setShader(blendShader);
this.set1i('uMainSampler1', 0);
this.set1i('uMainSampler2', 1);
this.set1f('uStrength', strength);
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, source1.texture);