JSDoc improvements

Author: photonstorm

src/gameobjects/pointlight/PointLight.js

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

src/math/RandomXYZW.js

@@ -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;

src/math/Vector4.js

@@ -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;

src/math/angle/ShortestBetween.js

@@ -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
  *

src/physics/arcade/World.js

@@ -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);

src/renderer/webgl/PipelineManager.js

@@ -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.
      *

src/renderer/webgl/pipelines/BitmapMaskPipeline.js

@@ -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.

src/renderer/webgl/pipelines/LightPipeline.js

@@ -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)

src/renderer/webgl/pipelines/PointLightPipeline.js

@@ -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;