diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/src/extras/MovieClip.js b/src/extras/MovieClip.js index a297dcd..b567a29 100644 --- a/src/extras/MovieClip.js +++ b/src/extras/MovieClip.js @@ -92,6 +92,13 @@ } }, + /** + * The array of textures used for this MovieClip + * + * @member + * @memberof MovieClip# + * + */ textures: { get: function () { @@ -148,7 +155,7 @@ this.currentFrame = frameNumber; - var round = Math.round(this.currentFrame); + var round = Math.floor(this.currentFrame); this.texture = this._textures[round % this._textures.length]; }; @@ -165,7 +172,6 @@ /* * Updates the object transform for rendering - * * @private */ MovieClip.prototype.update = function ( event ) diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/src/extras/MovieClip.js b/src/extras/MovieClip.js index a297dcd..b567a29 100644 --- a/src/extras/MovieClip.js +++ b/src/extras/MovieClip.js @@ -92,6 +92,13 @@ } }, + /** + * The array of textures used for this MovieClip + * + * @member + * @memberof MovieClip# + * + */ textures: { get: function () { @@ -148,7 +155,7 @@ this.currentFrame = frameNumber; - var round = Math.round(this.currentFrame); + var round = Math.floor(this.currentFrame); this.texture = this._textures[round % this._textures.length]; }; @@ -165,7 +172,6 @@ /* * Updates the object transform for rendering - * * @private */ MovieClip.prototype.update = function ( event ) diff --git a/src/extras/Rope.js b/src/extras/Rope.js index 47c8f48..8b85d60 100644 --- a/src/extras/Rope.js +++ b/src/extras/Rope.js @@ -6,17 +6,36 @@ * @namespace PIXI * @extends Strip * @param {Texture} texture - The texture to use on the rope. - * @param {Array} points - An array of {Point}. + * @param {Array} points - An array of {Point} objects. * */ function Rope(texture, points) { Strip.call(this, texture); + + /* + * @member {Array} An array of points that determine the rope + */ this.points = points; + /* + * @member {Float32Array} An array of vertices used to construct this rope. + */ this.vertices = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} The WebGL Uvs of the rope. + */ this.uvs = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} An array containing the color components + */ this.colors = new Float32Array(points.length * 2); + + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array(points.length * 2); this.refresh(); diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/src/extras/MovieClip.js b/src/extras/MovieClip.js index a297dcd..b567a29 100644 --- a/src/extras/MovieClip.js +++ b/src/extras/MovieClip.js @@ -92,6 +92,13 @@ } }, + /** + * The array of textures used for this MovieClip + * + * @member + * @memberof MovieClip# + * + */ textures: { get: function () { @@ -148,7 +155,7 @@ this.currentFrame = frameNumber; - var round = Math.round(this.currentFrame); + var round = Math.floor(this.currentFrame); this.texture = this._textures[round % this._textures.length]; }; @@ -165,7 +172,6 @@ /* * Updates the object transform for rendering - * * @private */ MovieClip.prototype.update = function ( event ) diff --git a/src/extras/Rope.js b/src/extras/Rope.js index 47c8f48..8b85d60 100644 --- a/src/extras/Rope.js +++ b/src/extras/Rope.js @@ -6,17 +6,36 @@ * @namespace PIXI * @extends Strip * @param {Texture} texture - The texture to use on the rope. - * @param {Array} points - An array of {Point}. + * @param {Array} points - An array of {Point} objects. * */ function Rope(texture, points) { Strip.call(this, texture); + + /* + * @member {Array} An array of points that determine the rope + */ this.points = points; + /* + * @member {Float32Array} An array of vertices used to construct this rope. + */ this.vertices = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} The WebGL Uvs of the rope. + */ this.uvs = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} An array containing the color components + */ this.colors = new Float32Array(points.length * 2); + + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array(points.length * 2); this.refresh(); diff --git a/src/extras/Strip.js b/src/extras/Strip.js index a6fa179..519821f 100644 --- a/src/extras/Strip.js +++ b/src/extras/Strip.js @@ -21,19 +21,36 @@ */ this.texture = texture; - // set up the main bits.. + /** + * The Uvs of the strip + * + * @member {Float32Array} + */ this.uvs = new Float32Array([0, 1, 1, 1, 1, 0, 0, 1]); + /** + * An array of vertices + * + * @member {Float32Array} + */ this.vertices = new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]); + /** + * The color components + * + * @member {Float32Array} + */ this.colors = new Float32Array([1, 1, 1, 1]); + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array([0, 1, 2, 3]); /** @@ -58,6 +75,11 @@ */ this.canvasPadding = 0; + /** + * The way the strip should be drawn, can be any of the Strip.DrawModes consts + * + * @member {number} + */ this.drawMode = Strip.DrawModes.TRIANGLE_STRIP; } @@ -69,7 +91,7 @@ /** * Renders the object using the WebGL renderer * - * @param renderer {WebGLRenderer} + * @param renderer {WebGLRenderer} a reference to the WebGL renderer */ Strip.prototype.renderWebGL = function (renderer) { @@ -100,6 +122,12 @@ //TODO check culling }; +/** + * Creates the buffers and (in the darkness) binds them + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._initWebGL = function (renderer) { // build the strip! @@ -123,6 +151,12 @@ gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, this.indices, gl.STATIC_DRAW); }; +/** + * Renders the strip ! + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._renderStrip = function (renderer) { var gl = renderer.gl; @@ -246,6 +280,12 @@ } }; +/** + * Draws the object in TRIANGLE_STRIP mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangleStrip = function (context) { // draw triangles!! @@ -263,6 +303,12 @@ } }; +/** + * Draws the object in triangle mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangles = function (context) { // draw triangles!! @@ -281,6 +327,17 @@ } }; +/** + * Draws one of the triangles that form this strip + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @param vertices {Float32Array} a reference to the the vertices of the strip + * @param uvs {Float32Array} a reference to the the vertices of the strip + * @param index0 {number} the index of the first vertex + * @param index1 {number} the index of the second vertex + * @param index2 {number} the index of the third vertex + * @private + */ Strip.prototype._renderCanvasDrawTriangle = function (context, vertices, uvs, index0, index1, index2) { var textureSource = this.texture.baseTexture.source; diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/src/extras/MovieClip.js b/src/extras/MovieClip.js index a297dcd..b567a29 100644 --- a/src/extras/MovieClip.js +++ b/src/extras/MovieClip.js @@ -92,6 +92,13 @@ } }, + /** + * The array of textures used for this MovieClip + * + * @member + * @memberof MovieClip# + * + */ textures: { get: function () { @@ -148,7 +155,7 @@ this.currentFrame = frameNumber; - var round = Math.round(this.currentFrame); + var round = Math.floor(this.currentFrame); this.texture = this._textures[round % this._textures.length]; }; @@ -165,7 +172,6 @@ /* * Updates the object transform for rendering - * * @private */ MovieClip.prototype.update = function ( event ) diff --git a/src/extras/Rope.js b/src/extras/Rope.js index 47c8f48..8b85d60 100644 --- a/src/extras/Rope.js +++ b/src/extras/Rope.js @@ -6,17 +6,36 @@ * @namespace PIXI * @extends Strip * @param {Texture} texture - The texture to use on the rope. - * @param {Array} points - An array of {Point}. + * @param {Array} points - An array of {Point} objects. * */ function Rope(texture, points) { Strip.call(this, texture); + + /* + * @member {Array} An array of points that determine the rope + */ this.points = points; + /* + * @member {Float32Array} An array of vertices used to construct this rope. + */ this.vertices = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} The WebGL Uvs of the rope. + */ this.uvs = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} An array containing the color components + */ this.colors = new Float32Array(points.length * 2); + + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array(points.length * 2); this.refresh(); diff --git a/src/extras/Strip.js b/src/extras/Strip.js index a6fa179..519821f 100644 --- a/src/extras/Strip.js +++ b/src/extras/Strip.js @@ -21,19 +21,36 @@ */ this.texture = texture; - // set up the main bits.. + /** + * The Uvs of the strip + * + * @member {Float32Array} + */ this.uvs = new Float32Array([0, 1, 1, 1, 1, 0, 0, 1]); + /** + * An array of vertices + * + * @member {Float32Array} + */ this.vertices = new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]); + /** + * The color components + * + * @member {Float32Array} + */ this.colors = new Float32Array([1, 1, 1, 1]); + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array([0, 1, 2, 3]); /** @@ -58,6 +75,11 @@ */ this.canvasPadding = 0; + /** + * The way the strip should be drawn, can be any of the Strip.DrawModes consts + * + * @member {number} + */ this.drawMode = Strip.DrawModes.TRIANGLE_STRIP; } @@ -69,7 +91,7 @@ /** * Renders the object using the WebGL renderer * - * @param renderer {WebGLRenderer} + * @param renderer {WebGLRenderer} a reference to the WebGL renderer */ Strip.prototype.renderWebGL = function (renderer) { @@ -100,6 +122,12 @@ //TODO check culling }; +/** + * Creates the buffers and (in the darkness) binds them + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._initWebGL = function (renderer) { // build the strip! @@ -123,6 +151,12 @@ gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, this.indices, gl.STATIC_DRAW); }; +/** + * Renders the strip ! + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._renderStrip = function (renderer) { var gl = renderer.gl; @@ -246,6 +280,12 @@ } }; +/** + * Draws the object in TRIANGLE_STRIP mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangleStrip = function (context) { // draw triangles!! @@ -263,6 +303,12 @@ } }; +/** + * Draws the object in triangle mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangles = function (context) { // draw triangles!! @@ -281,6 +327,17 @@ } }; +/** + * Draws one of the triangles that form this strip + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @param vertices {Float32Array} a reference to the the vertices of the strip + * @param uvs {Float32Array} a reference to the the vertices of the strip + * @param index0 {number} the index of the first vertex + * @param index1 {number} the index of the second vertex + * @param index2 {number} the index of the third vertex + * @private + */ Strip.prototype._renderCanvasDrawTriangle = function (context, vertices, uvs, index0, index1, index2) { var textureSource = this.texture.baseTexture.source; diff --git a/src/extras/StripShader.js b/src/extras/StripShader.js index bb12757..acbe147 100644 --- a/src/extras/StripShader.js +++ b/src/extras/StripShader.js @@ -3,7 +3,8 @@ /** * @class * @namespace PIXI - * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. + * @param shaderManager {ShaderManager} The WebGL shader manager this shader works for. + * @extends Shader */ function StripShader(shaderManager) { diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/src/extras/MovieClip.js b/src/extras/MovieClip.js index a297dcd..b567a29 100644 --- a/src/extras/MovieClip.js +++ b/src/extras/MovieClip.js @@ -92,6 +92,13 @@ } }, + /** + * The array of textures used for this MovieClip + * + * @member + * @memberof MovieClip# + * + */ textures: { get: function () { @@ -148,7 +155,7 @@ this.currentFrame = frameNumber; - var round = Math.round(this.currentFrame); + var round = Math.floor(this.currentFrame); this.texture = this._textures[round % this._textures.length]; }; @@ -165,7 +172,6 @@ /* * Updates the object transform for rendering - * * @private */ MovieClip.prototype.update = function ( event ) diff --git a/src/extras/Rope.js b/src/extras/Rope.js index 47c8f48..8b85d60 100644 --- a/src/extras/Rope.js +++ b/src/extras/Rope.js @@ -6,17 +6,36 @@ * @namespace PIXI * @extends Strip * @param {Texture} texture - The texture to use on the rope. - * @param {Array} points - An array of {Point}. + * @param {Array} points - An array of {Point} objects. * */ function Rope(texture, points) { Strip.call(this, texture); + + /* + * @member {Array} An array of points that determine the rope + */ this.points = points; + /* + * @member {Float32Array} An array of vertices used to construct this rope. + */ this.vertices = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} The WebGL Uvs of the rope. + */ this.uvs = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} An array containing the color components + */ this.colors = new Float32Array(points.length * 2); + + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array(points.length * 2); this.refresh(); diff --git a/src/extras/Strip.js b/src/extras/Strip.js index a6fa179..519821f 100644 --- a/src/extras/Strip.js +++ b/src/extras/Strip.js @@ -21,19 +21,36 @@ */ this.texture = texture; - // set up the main bits.. + /** + * The Uvs of the strip + * + * @member {Float32Array} + */ this.uvs = new Float32Array([0, 1, 1, 1, 1, 0, 0, 1]); + /** + * An array of vertices + * + * @member {Float32Array} + */ this.vertices = new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]); + /** + * The color components + * + * @member {Float32Array} + */ this.colors = new Float32Array([1, 1, 1, 1]); + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array([0, 1, 2, 3]); /** @@ -58,6 +75,11 @@ */ this.canvasPadding = 0; + /** + * The way the strip should be drawn, can be any of the Strip.DrawModes consts + * + * @member {number} + */ this.drawMode = Strip.DrawModes.TRIANGLE_STRIP; } @@ -69,7 +91,7 @@ /** * Renders the object using the WebGL renderer * - * @param renderer {WebGLRenderer} + * @param renderer {WebGLRenderer} a reference to the WebGL renderer */ Strip.prototype.renderWebGL = function (renderer) { @@ -100,6 +122,12 @@ //TODO check culling }; +/** + * Creates the buffers and (in the darkness) binds them + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._initWebGL = function (renderer) { // build the strip! @@ -123,6 +151,12 @@ gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, this.indices, gl.STATIC_DRAW); }; +/** + * Renders the strip ! + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._renderStrip = function (renderer) { var gl = renderer.gl; @@ -246,6 +280,12 @@ } }; +/** + * Draws the object in TRIANGLE_STRIP mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangleStrip = function (context) { // draw triangles!! @@ -263,6 +303,12 @@ } }; +/** + * Draws the object in triangle mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangles = function (context) { // draw triangles!! @@ -281,6 +327,17 @@ } }; +/** + * Draws one of the triangles that form this strip + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @param vertices {Float32Array} a reference to the the vertices of the strip + * @param uvs {Float32Array} a reference to the the vertices of the strip + * @param index0 {number} the index of the first vertex + * @param index1 {number} the index of the second vertex + * @param index2 {number} the index of the third vertex + * @private + */ Strip.prototype._renderCanvasDrawTriangle = function (context, vertices, uvs, index0, index1, index2) { var textureSource = this.texture.baseTexture.source; diff --git a/src/extras/StripShader.js b/src/extras/StripShader.js index bb12757..acbe147 100644 --- a/src/extras/StripShader.js +++ b/src/extras/StripShader.js @@ -3,7 +3,8 @@ /** * @class * @namespace PIXI - * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. + * @param shaderManager {ShaderManager} The WebGL shader manager this shader works for. + * @extends Shader */ function StripShader(shaderManager) { diff --git a/src/extras/TilingSprite.js b/src/extras/TilingSprite.js index 18955c0..bbd1f56 100644 --- a/src/extras/TilingSprite.js +++ b/src/extras/TilingSprite.js @@ -19,8 +19,6 @@ { core.Sprite.call(this, texture); - - /** * The scaling of the image that is being tiled * @@ -36,14 +34,13 @@ */ this.tilePosition = new core.math.Point(0,0); - - ///// private /** * The with of the tiling sprite * * @member {number} + * @private */ this._width = width || 100; @@ -51,6 +48,7 @@ * The height of the tiling sprite * * @member {number} + * @private */ this._height = height || 100; @@ -58,13 +56,33 @@ * A point that represents the scale of the texture object * * @member {Point} + * @private */ this._tileScaleOffset = new core.math.Point(1,1); + /** + * + * + * @member {boolean} + * @private + */ this._tilingTexture = null; + + /** + * + * + * @member {boolean} + * @private + */ this._refreshTexture = false; + /** + * An internal WebGL UV cache. + * + * @member {TextureUvs} + * @private + */ this._uvs = new TextureUvs(); } @@ -187,7 +205,7 @@ /** * Renders the object using the Canvas renderer * - * @param renderer {CanvasRenderer} + * @param renderer {CanvasRenderer} a reference to the canvas renderer */ TilingSprite.prototype.renderCanvas = function (renderer) { @@ -359,7 +377,9 @@ }; /** - * + * Creates the tiling texture + * @param renderer {CanvasRenderer|WebGLRenderer} a reference to the current renderer + * @param texture {Texture} The texture to use to generate the tiling texture * @param forcePowerOfTwo {boolean} Whether we want to force the texture to be a power of two */ TilingSprite.prototype.generateTilingTexture = function (renderer, texture, forcePowerOfTwo) @@ -421,6 +441,10 @@ }; +/** + * Checks if a point is inside this tiling sprite + * @param point {Point} the point to check + */ TilingSprite.prototype.hitTest = function( point ) { this.worldTransform.applyInverse(point, tempPoint); @@ -443,7 +467,10 @@ return false; }; - +/** + * Destroys this tiling sprite + * + */ TilingSprite.prototype.destroy = function () { core.Sprite.prototype.destroy.call(this); diff --git a/gulp/tasks/jsdoc.js b/gulp/tasks/jsdoc.js index e69de29..b809f13 100644 --- a/gulp/tasks/jsdoc.js +++ b/gulp/tasks/jsdoc.js @@ -0,0 +1,44 @@ +var gulp = require('gulp'), + jsdoc = require('gulp-jsdoc'), + del = require('del'); + + +gulp.task('jsdocs',function(){ + + // here we use a globbing pattern to match everything inside the 'documentation' folder + var folders = [ + './documentation/**' + ]; + + + var docStrapTemplate = { + // docstrap is included in gulp-jsdoc, thanks guys + path : "ink-docstrap", + // the <title> of the web page + systemName : "The official pixi.js documentaion", + // A left-aligned message on the footer + footer : "Made with ♥ by <a href='http://goodboydigital.com'>Goodboy Digital</a>", + // The centred copyright message + copyright : "© Goodboy Digital Ltd and all the pixi.js contributors", + navType : "vertical", + theme : "readable", + // TODO add + analytics : {"ua":"UA-XXXXX-XXX", "domain":"XXXX"}, + outputSourceFiles : true, + linenums : true, + collapseSymbols : false, + inverseNav : false + } + + function deleteCallback(error,deletedFiles) { + // When the previous docs are deleted, run gulp-jsdoc + // + return gulp.src('./src/core/display/*.js') + .pipe( jsdoc('./documentation',docStrapTemplate) ) + } + + + // deletes the docs folder and re-generates the documentation + del(folders,deleteCallback); + +}); \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index 3d29ac5..4ff5a4e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -30,3 +30,6 @@ // default task gulp.task('default', ['jshint', 'build']); + +// you can directly use 'gulp jsdocs' to generate the docs +gulp.task('docs',['jsdocs']); \ No newline at end of file diff --git a/package.json b/package.json index 0f6b10f..0538495 100644 --- a/package.json +++ b/package.json @@ -26,12 +26,15 @@ "del": "^1.1.0", "gulp": "^3.8.10", "gulp-cached": "^1.0.1", + "gulp-concat": "^2.5.2", + "gulp-debug": "^2.0.0", + "gulp-jsdoc": "^0.1.4", "gulp-jshint": "^1.9.0", "gulp-plumber": "^0.6.6", "gulp-rename": "^1.2.0", "gulp-uglify": "^1.0.2", "gulp-util": "^3.0.1", - "ink-docstrap": "^0.4.12", + "ink-docstrap": "^0.5.2", "jsdoc": "^3.3.0-alpha13", "jshint-summary": "^0.4.0", "karma": "^0.12.28", diff --git a/src/core/display/Container.js b/src/core/display/Container.js index 266221f..ef16ae1 100644 --- a/src/core/display/Container.js +++ b/src/core/display/Container.js @@ -152,7 +152,7 @@ if (index1 < 0 || index2 < 0) { - throw new Error('swapChildren: Both the supplied DisplayObjects must be a child of the caller.'); + throw new Error('swapChildren: Both the supplied DisplayObjects must be children of the caller.'); } this.children[index1] = child2; @@ -199,14 +199,14 @@ /** * Returns the child at the specified index * - * @param index {Number} The index to get the child from + * @param index {Number} The index to get the child at * @return {DisplayObject} The child at the given index, if any. */ Container.prototype.getChildAt = function (index) { if (index < 0 || index >= this.children.length) { - throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject must be a child of the caller'); + throw new Error('getChildAt: Supplied index ' + index + ' does not exist in the child list, or the supplied DisplayObject is not a child of the caller'); } return this.children[index]; @@ -280,13 +280,13 @@ }; /** - * Useful function that returns a texture of the displayObject object that can then be used to create sprites + * Useful function that returns a texture of the display object that can then be used to create sprites * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. * @param resolution {Number} The resolution of the texture being generated * @param scaleMode {Number} See {@link SCALE_MODES} for possible values - * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. - * @return {Texture} a texture of the graphics object + * @return {Texture} a texture of the display object */ Container.prototype.generateTexture = function (renderer, resolution, scaleMode) { @@ -488,9 +488,9 @@ } }; -Container.prototype._renderWebGL = function (/* renderer */) +Container.prototype._renderWebGL = function (renderer) { - // this is where content itself gets renderd.. + // this is where content itself gets rendered... }; diff --git a/src/core/display/DisplayObject.js b/src/core/display/DisplayObject.js index 243a75b..9b45b73 100644 --- a/src/core/display/DisplayObject.js +++ b/src/core/display/DisplayObject.js @@ -280,7 +280,7 @@ // temporary matrix variables var a, b, c, d, tx, ty; - // so if rotation is between 0 then we can simplify the multiplication process.. + // so if rotation is between 0 then we can simplify the multiplication process... if (this.rotation % math.PI_2) { // check to see if the rotation is the same as the previous render. This means we only need to use sin and cos when rotation actually changes @@ -344,13 +344,12 @@ /** * * - * * Retrieves the bounds of the displayObject as a rectangle object * * @param matrix {Matrix} * @return {Rectangle} the rectangular bounding area */ -DisplayObject.prototype.getBounds = function (/* matrix */) +DisplayObject.prototype.getBounds = function (matrix) { return math.Rectangle.EMPTY; }; @@ -373,7 +372,7 @@ */ DisplayObject.prototype.toGlobal = function (position) { - // don't need to u[date the lot + // don't need to update the lot this.displayObjectUpdateTransform(); return this.worldTransform.apply(position); }; @@ -403,7 +402,7 @@ * @param renderer {WebGLRenderer} The renderer * @private */ -DisplayObject.prototype.renderWebGL = function (/* renderer */) +DisplayObject.prototype.renderWebGL = function (renderer) { // OVERWRITE; }; @@ -414,11 +413,19 @@ * @param renderer {CanvasRenderer} The renderer * @private */ -DisplayObject.prototype.renderCanvas = function (/* renderer */) +DisplayObject.prototype.renderCanvas = function (renderer) { // OVERWRITE; }; - +/** + * Useful function that returns a texture of the display object that can then be used to create sprites + * This can be quite useful if your displayObject is static / complicated and needs to be reused multiple times. + * + * @param renderer {CanvasRenderer|WebGLRenderer} The renderer used to generate the texture. + * @param resolution {Number} The resolution of the texture being generated + * @param scaleMode {Number} See {@link SCALE_MODES} for possible values + * @return {Texture} a texture of the display object + */ DisplayObject.prototype.generateTexture = function (renderer, resolution, scaleMode) { var bounds = this.getLocalBounds(); diff --git a/src/core/graphics/Graphics.js b/src/core/graphics/Graphics.js index fea2126..bb1c13e 100644 --- a/src/core/graphics/Graphics.js +++ b/src/core/graphics/Graphics.js @@ -3,14 +3,13 @@ Texture = require('../textures/Texture'), CanvasBuffer = require('../renderers/canvas/utils/CanvasBuffer'), CanvasGraphics = require('../renderers/canvas/utils/CanvasGraphics'), - // WebGLGraphics = require('../renderers/webgl/utils/WebGLGraphics'), GraphicsData = require('./GraphicsData'), math = require('../math'), CONST = require('../const'); /** * The Graphics class contains methods used to draw primitive shapes such as lines, circles and - * rectangles to the display, and color and fill them. + * rectangles to the display, and to color and fill them. * * @class * @extends Container @@ -160,7 +159,7 @@ * * @return {Graphics} */ -GraphicsData.prototype.clone = function () +Graphics.prototype.clone = function () { var clone = new Graphics(); @@ -1069,7 +1068,7 @@ /** * Draws the given shape to this Graphics object. Can be any of Circle, Rectangle, Ellipse, Line or Polygon. * - * @param {Circle|Rectangle|Ellipse|Line|Polygon} shape The Shape object to draw. + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. * @return {GraphicsData} The generated GraphicsData object. */ Graphics.prototype.drawShape = function (shape) diff --git a/src/core/graphics/GraphicsData.js b/src/core/graphics/GraphicsData.js index 788f6f2..809d8c3 100644 --- a/src/core/graphics/GraphicsData.js +++ b/src/core/graphics/GraphicsData.js @@ -3,20 +3,62 @@ * * @class * @namespace PIXI + * @param lineWidth {number} the width of the line to draw + * @param lineColor {number} the color of the line to draw + * @param lineAlpha {number} the alpha of the line to draw + * @param fillColor {number} the color of the fill + * @param fillAlpha {number} the alpha of the fill + * @param fill {boolean} whether or not the shape is filled with a colour + * @param shape {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. */ function GraphicsData(lineWidth, lineColor, lineAlpha, fillColor, fillAlpha, fill, shape) { + /* + * @member {number} the width of the line to draw + */ this.lineWidth = lineWidth; + + /* + * @member {number} the color of the line to draw + */ this.lineColor = lineColor; + /* + * @member {number} the alpha of the line to draw + */ this.lineAlpha = lineAlpha; + /* + * @member {number} cached tint of the line to draw + */ this._lineTint = lineColor; + /* + * @member {number} the color of the fill + */ this.fillColor = fillColor; + + /* + * @member {number} the alpha of the fill + */ this.fillAlpha = fillAlpha; + + /* + * @member {number} cached tint of the fill + */ this._fillTint = fillColor; + + /* + * @member {boolean} whether or not the shape is filled with a colour + */ this.fill = fill; + /* + * @member {Circle|Rectangle|Ellipse|Line|Polygon} The shape object to draw. + */ this.shape = shape; + + /* + * @member {number} The type of the shape, see the Const.Shapes file for all the existing types, + */ this.type = shape.type; } diff --git a/src/core/graphics/webgl/GraphicsRenderer.js b/src/core/graphics/webgl/GraphicsRenderer.js index f0c5ffd..9dfcaad 100644 --- a/src/core/graphics/webgl/GraphicsRenderer.js +++ b/src/core/graphics/webgl/GraphicsRenderer.js @@ -11,6 +11,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this object renderer works for. */ function GraphicsRenderer(renderer) @@ -120,7 +121,6 @@ * * @private * @param graphicsData {Graphics} The graphics object to update - * @param gl {WebGLContext} the current WebGL drawing context */ GraphicsRenderer.prototype.updateGraphics = function(graphics) { @@ -251,8 +251,8 @@ * * * @private - * @param webGL {WebGLContext} - * @param type {number} + * @param webGL {WebGLRenderingContext} the current WebGL drawing context + * @param type {number} TODO @Alvin */ GraphicsRenderer.prototype.switchMode = function (webGL, type) { @@ -286,7 +286,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRectangle = function (graphicsData, webGLData) { @@ -352,7 +352,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildRoundedRectangle = function (graphicsData, webGLData) { @@ -429,7 +429,7 @@ * @param cpY {number} Control point y * @param toX {number} Destination point x * @param toY {number} Destination point y - * @return {number[]} + * @return {number[]} an array of points */ GraphicsRenderer.prototype.quadraticBezierCurve = function (fromX, fromY, cpX, cpY, toX, toY) { @@ -473,7 +473,7 @@ * * @private * @param graphicsData {Graphics} The graphics object to draw - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildCircle = function (graphicsData, webGLData) { @@ -554,7 +554,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildLine = function (graphicsData, webGLData) { @@ -769,7 +769,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildComplexPoly = function (graphicsData, webGLData) { @@ -831,7 +831,7 @@ * * @private * @param graphicsData {Graphics} The graphics object containing all the necessary properties - * @param webGLData {object} + * @param webGLData {object} an object containing all the webGL-specific information to create this shape */ GraphicsRenderer.prototype.buildPoly = function (graphicsData, webGLData) { diff --git a/src/core/graphics/webgl/WebGLGraphicsData.js b/src/core/graphics/webgl/WebGLGraphicsData.js index 41be102..45132d8 100644 --- a/src/core/graphics/webgl/WebGLGraphicsData.js +++ b/src/core/graphics/webgl/WebGLGraphicsData.js @@ -1,18 +1,55 @@ /** - * @class + * An object containing WebGL specific properties to be used by the WebGL renderer + * + * @class + * @param gl {WebGLRenderingContext} the current WebGL drawing context * @private */ function WebGLGraphicsData(gl) { + + /* + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; //TODO does this need to be split before uploding?? + /* + * @member {Array} An array of color components (r,g,b) + */ this.color = [0,0,0]; // color split! + + /* + * @member {Array} An array of points to draw + */ this.points = []; + + /* + * @member {Array} The indices of the vertices + */ this.indices = []; + /* + * @member {WebGLBuffer} The main buffer + */ this.buffer = gl.createBuffer(); + + /* + * @member {WebGLBuffer} The index buffer + */ this.indexBuffer = gl.createBuffer(); + + /* + * @member {number} todo @alvin + */ this.mode = 1; + + /* + * @member {number} The alpha of the graphics + */ this.alpha = 1; + + /* + * @member {boolean} Whether this graphics is dirty or not + */ this.dirty = true; } @@ -20,7 +57,7 @@ module.exports = WebGLGraphicsData; /** - * + * Resets the vertices and the indices */ WebGLGraphicsData.prototype.reset = function () { this.points = []; @@ -28,7 +65,7 @@ }; /** - * + * Binds the buffers and uploads the data */ WebGLGraphicsData.prototype.upload = function () { var gl = this.gl; diff --git a/src/core/index.js b/src/core/index.js index 83721d5..b2893e6 100644 --- a/src/core/index.js +++ b/src/core/index.js @@ -65,7 +65,7 @@ * @param [options.preserveDrawingBuffer=false] {boolean} enables drawing buffer preservation, enable this if you * need to call toDataUrl on the webgl context * @param [options.resolution=1] {number} the resolution of the renderer retina would be 2 - * @param [noWebGL=false] {Boolean} prevents selection of WebGL renderer, even if such is present + * @param [noWebGL=false] {boolean} prevents selection of WebGL renderer, even if such is present * * @return {WebGLRenderer|CanvasRenderer} Returns WebGL renderer if available, otherwise CanvasRenderer */ diff --git a/src/core/math/Matrix.js b/src/core/math/Matrix.js index ba28c1c..e625842 100644 --- a/src/core/math/Matrix.js +++ b/src/core/math/Matrix.js @@ -1,7 +1,7 @@ var Point = require('./Point'); /** - * The Matrix class is now an object, which makes it a lot faster, + * The pixi Matrix class as an object, which makes it a lot faster, * here is a representation of it : * | a | b | tx| * | c | d | ty| @@ -271,7 +271,11 @@ return this; }; - +/** + * Inverts this matrix + * + * @return {Matrix} This matrix. Good for chaining method calls. + */ Matrix.prototype.invert = function() { var a1 = this.a; @@ -309,7 +313,11 @@ return this; }; - +/** + * Creates a new Matrix object with the same values as this one. + * + * @return {Matrix} A copy of this matrix. Good for chaining method calls. + */ Matrix.prototype.clone = function () { var matrix = new Matrix(); @@ -323,6 +331,11 @@ return matrix; }; +/** + * Changes the values of the given matrix to be the same as the ones in this matrix + * + * @return {Matrix} The matrix given in parameter with its values updated. + */ Matrix.prototype.copy = function (matrix) { matrix.a = this.a; @@ -335,6 +348,11 @@ return matrix; }; - +/** + * A default (identity) matrix + */ Matrix.IDENTITY = new Matrix(); +/** + * A temp matrix + */ Matrix.TEMP_MATRIX = new Matrix(); diff --git a/src/core/math/index.js b/src/core/math/index.js index cc176e9..0e7a562 100644 --- a/src/core/math/index.js +++ b/src/core/math/index.js @@ -3,7 +3,7 @@ */ module.exports = { /** - * @property {number} PI_2 - Math.PI x 2 + * @property {number} PI_2 - Two Pi * @constant * @static */ diff --git a/src/core/math/shapes/RoundedRectangle.js b/src/core/math/shapes/RoundedRectangle.js index 7bf6411..7ec1eb4 100644 --- a/src/core/math/shapes/RoundedRectangle.js +++ b/src/core/math/shapes/RoundedRectangle.js @@ -1,7 +1,7 @@ var CONST = require('../../const'); /** - * The Rounded Rectangle object is an area defined by its position and has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height. + * The Rounded Rectangle object is an area that has nice rounded corners, as indicated by its top-left corner point (x, y) and by its width and its height and its radius. * * @class * @namespace PIXI diff --git a/src/core/particles/ParticleContainer.js b/src/core/particles/ParticleContainer.js index 464edcc..27664c2 100644 --- a/src/core/particles/ParticleContainer.js +++ b/src/core/particles/ParticleContainer.js @@ -21,7 +21,10 @@ * And here you have a hundred sprites that will be renderer at the speed of light. * * @class + * @extends Container * @namespace PIXI + * + * @param size {number} The number of images in the SpriteBatch before it flushes. */ function ParticleContainer(size, properties) { @@ -55,7 +58,7 @@ }; /** - * Renders the object using the WebGL renderer + * Renders the container using the WebGL renderer * * @param renderer {WebGLRenderer} The webgl renderer * @private @@ -71,6 +74,13 @@ renderer.plugins.particle.render( this ); }; +/** + * Adds a child to this particle container at a specified index. If the index is out of bounds an error will be thrown + * + * @param child {DisplayObject} The child to add + * @param index {Number} The index to place the child in + * @return {DisplayObject} The child that was added. + */ ParticleContainer.prototype.addChildAt = function (child, index) { // prevent adding self as child diff --git a/src/core/particles/webgl/ParticleBuffer.js b/src/core/particles/webgl/ParticleBuffer.js index e33f4f4..73eae2e 100644 --- a/src/core/particles/webgl/ParticleBuffer.js +++ b/src/core/particles/webgl/ParticleBuffer.js @@ -19,6 +19,9 @@ */ function ParticleBuffer(gl, properties, size) { + /** + * @member {WebGLRenderingContext} the current WebGL drawing context + */ this.gl = gl; /** @@ -42,7 +45,18 @@ */ this.size = size; + /** + * + * + * @member {Array} + */ this.dynamicProperties = []; + + /** + * + * + * @member {Array} + */ this.staticProperties = []; for (var i = 0; i < properties.length; i++) @@ -78,7 +92,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ ParticleBuffer.prototype.initBuffers = function () { diff --git a/src/core/particles/webgl/ParticleRenderer.js b/src/core/particles/webgl/ParticleRenderer.js index 8c48ffb..4b46eb0 100644 --- a/src/core/particles/webgl/ParticleRenderer.js +++ b/src/core/particles/webgl/ParticleRenderer.js @@ -75,10 +75,10 @@ WebGLRenderer.registerPlugin('particle', ParticleRenderer); /** - * Sets up the renderer context and necessary buffers. + * When there is a WebGL context change * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * */ ParticleRenderer.prototype.onContextChange = function () { @@ -164,7 +164,7 @@ /** * Renders the sprite object. * - * @param sprite {Sprite} the sprite to render when using this Particle + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer */ ParticleRenderer.prototype.render = function ( container ) { @@ -247,6 +247,11 @@ container._updateStatic = false; }; +/** + * Creates one particle buffer for each child in the container we want to render and updates internal properties + * + * @param container {Container || Sprite} the sprite to render using this ParticleRenderer + */ ParticleRenderer.prototype.generateBuffers = function ( container ) { var gl = this.renderer.gl, @@ -269,7 +274,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their vertices uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadVerticies = function (children, startIndex, amount, array, stride, offset) { var sprite, @@ -323,7 +336,15 @@ }; - +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their positions uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadPosition = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -347,6 +368,15 @@ }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their rotation uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadRotation = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -363,6 +393,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their Uvs uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadUvs = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -405,6 +444,15 @@ } }; +/** + * + * @param children {Array} the array of display objects to render + * @param startIndex {number} the index to start from in the children array + * @param amount {number} the amount of children that will have their alpha uploaded + * @param array {Array} + * @param stride {number} + * @param offset {number} + */ ParticleRenderer.prototype.uploadAlpha = function (children,startIndex, amount, array, stride, offset) { for (var i = 0; i < amount; i++) @@ -432,5 +480,3 @@ //TODO implement this! }; - - diff --git a/src/core/particles/webgl/ParticleShader.js b/src/core/particles/webgl/ParticleShader.js index 97836c2..096aef6 100644 --- a/src/core/particles/webgl/ParticleShader.js +++ b/src/core/particles/webgl/ParticleShader.js @@ -2,7 +2,7 @@ /** * @class - * @extends Shader + * @extends TextureShader * @namespace PIXI * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. */ diff --git a/src/core/renderers/canvas/utils/CanvasBuffer.js b/src/core/renderers/canvas/utils/CanvasBuffer.js index ed9c248..7d06c36 100644 --- a/src/core/renderers/canvas/utils/CanvasBuffer.js +++ b/src/core/renderers/canvas/utils/CanvasBuffer.js @@ -87,6 +87,10 @@ this.canvas.height = height; }; +/** + * Destroys this canvas. + * + */ CanvasBuffer.prototype.destroy = function () { this.context = null; diff --git a/src/core/renderers/canvas/utils/CanvasGraphics.js b/src/core/renderers/canvas/utils/CanvasGraphics.js index 3f2a91f..f0bccfd 100644 --- a/src/core/renderers/canvas/utils/CanvasGraphics.js +++ b/src/core/renderers/canvas/utils/CanvasGraphics.js @@ -2,7 +2,7 @@ /** * A set of functions used by the canvas renderer to draw the primitive graphics data. - * + * @static * @namespace PIXI */ var CanvasGraphics = module.exports = {}; @@ -293,6 +293,13 @@ } }; +/* + * Updates the tint of a graphics object + * + * @private + * @param graphics {Graphics} the graphics that will have its tint updated + * + */ CanvasGraphics.updateGraphicsTint = function (graphics) { if (graphics.tint === 0xFFFFFF) diff --git a/src/core/renderers/canvas/utils/CanvasTinter.js b/src/core/renderers/canvas/utils/CanvasTinter.js index d2fb1bc..272c7c2 100644 --- a/src/core/renderers/canvas/utils/CanvasTinter.js +++ b/src/core/renderers/canvas/utils/CanvasTinter.js @@ -2,7 +2,7 @@ /** * Utility methods for Sprite/Texture tinting. - * + * @static * @namespace PIXI */ var CanvasTinter = module.exports = {}; diff --git a/src/core/renderers/webgl/WebGLRenderer.js b/src/core/renderers/webgl/WebGLRenderer.js index ccbb887..9e56169 100644 --- a/src/core/renderers/webgl/WebGLRenderer.js +++ b/src/core/renderers/webgl/WebGLRenderer.js @@ -114,9 +114,16 @@ */ this.blendModeManager = new BlendModeManager(this); + /** + * Holds the current render target + * @member {Object} + */ this.currentRenderTarget = this.renderTarget; - + /** + * + * @member {ObjectRenderer} @alvin + */ this.currentRenderer = new ObjectRenderer(this); this.initPlugins(); @@ -127,6 +134,10 @@ // map some webGL blend modes.. this._mapBlendModes(); + /** + * An array of render targets + * @member {Array} TODO @alvin + */ this._renderTargetStack = []; } @@ -253,6 +264,12 @@ this.currentRenderer.flush(); }; +/** + * Changes the current renderer to the one given in parameter + * + * @param objectRenderer {Object} TODO @alvin + * + */ WebGLRenderer.prototype.setObjectRenderer = function (objectRenderer) { if (this.currentRenderer === objectRenderer) @@ -265,6 +282,12 @@ this.currentRenderer.start(); }; +/** + * Changes the current render target to the one given in parameter + * + * @param renderTarget {Object} the new render target + * + */ WebGLRenderer.prototype.setRenderTarget = function (renderTarget) { // TODO - maybe down the line this should be a push pos thing? Leaving for now though. @@ -345,6 +368,11 @@ return texture._glTextures[gl.id]; }; +/** + * Deletes the texture from WebGL + * + * @param texture {BaseTexture|Texture} the texture to destroy + */ WebGLRenderer.prototype.destroyTexture = function (texture) { texture = texture.baseTexture || texture; diff --git a/src/core/renderers/webgl/shaders/Shader.js b/src/core/renderers/webgl/shaders/Shader.js index db2baee..73b785e 100644 --- a/src/core/renderers/webgl/shaders/Shader.js +++ b/src/core/renderers/webgl/shaders/Shader.js @@ -24,7 +24,7 @@ this.uuid = utils.uuid(); /** - * @member {WebGLContext} + * @member {WebGLRenderingContext} * @readonly */ this.gl = shaderManager.renderer.gl; diff --git a/src/core/renderers/webgl/utils/RenderTarget.js b/src/core/renderers/webgl/utils/RenderTarget.js index 97d7af1..c64e306 100644 --- a/src/core/renderers/webgl/utils/RenderTarget.js +++ b/src/core/renderers/webgl/utils/RenderTarget.js @@ -11,7 +11,7 @@ /** * @class FrameBuffer * @constructor -* @param gl {WebGLContext} the current WebGL drawing context +* @param gl {WebGLRenderingContext} the current WebGL drawing context * @param width {Number} the horizontal range of the filter * @param height {Number} the vertical range of the filter * @param scaleMode {Number} See {{#crossLink "PIXI/scaleModes:property"}}PIXI.scaleModes{{/crossLink}} for possible values @@ -22,7 +22,7 @@ /** * @property gl - * @type WebGLContext + * @type WebGLRenderingContext */ this.gl = gl; diff --git a/src/core/sprites/Sprite.js b/src/core/sprites/Sprite.js index 1f408c9..32a7bf2 100644 --- a/src/core/sprites/Sprite.js +++ b/src/core/sprites/Sprite.js @@ -26,8 +26,8 @@ /** * The anchor sets the origin point of the texture. * The default is 0,0 this means the texture's origin is the top left - * Setting than anchor to 0.5,0.5 means the textures origin is centered - * Setting the anchor to 1,1 would mean the textures origin points will be the bottom right corner + * Setting the anchor to 0.5,0.5 means the texture's origin is centered + * Setting the anchor to 1,1 would mean the texture's origin point will be the bottom right corner * * @member {Point} */ @@ -86,6 +86,12 @@ this.texture = texture || Texture.EMPTY; } +/** + * Destroys this sprite and optionally its texture + * + * @param destroyTexture {boolean} Should it destroy the current texture of the sprite as well + * @param destroyBaseTexture {boolean} Should it destroy the base texture of the sprite as well + */ Sprite.prototype.destroy = function (destroyTexture, destroyBaseTexture) { Container.prototype.destroy.call(this); @@ -199,6 +205,12 @@ } }; +/** +* +* Renders the object using the WebGL renderer +* +* @param renderer {WebGLRenderer} +*/ Sprite.prototype._renderWebGL = function (renderer) { renderer.setObjectRenderer(renderer.plugins.sprite); diff --git a/src/core/sprites/webgl/SpriteRenderer.js b/src/core/sprites/webgl/SpriteRenderer.js index 1619596..e90d550 100644 --- a/src/core/sprites/webgl/SpriteRenderer.js +++ b/src/core/sprites/webgl/SpriteRenderer.js @@ -19,6 +19,7 @@ * @class * @private * @namespace PIXI + * @extends ObjectRenderer * @param renderer {WebGLRenderer} The renderer this sprite batch works for. */ function SpriteRenderer(renderer) @@ -66,7 +67,7 @@ this.positions = new Float32Array(this.vertices); /** - * View on the vertices as a Uint32Array + * Holds the color components * * @member {Uint32Array} */ @@ -164,7 +165,7 @@ * Sets up the renderer context and necessary buffers. * * @private - * @param gl {WebGLContext} the current WebGL drawing context + * @param gl {WebGLRenderingContext} the current WebGL drawing context */ SpriteRenderer.prototype.onContextChange = function () { diff --git a/src/core/textures/BaseTexture.js b/src/core/textures/BaseTexture.js index c547872..f28bdfa 100644 --- a/src/core/textures/BaseTexture.js +++ b/src/core/textures/BaseTexture.js @@ -9,6 +9,7 @@ * @namespace PIXI * @param source {Image|Canvas} the source object of the texture. * @param [scaleMode=scaleModes.DEFAULT] {number} See {@link SCALE_MODES} for possible values + * @param resolution {number} the resolution of the texture for devices with different pixel ratios */ function BaseTexture(source, scaleMode, resolution) { @@ -39,7 +40,19 @@ // TODO docs // used to store the actual dimensions of the source + /** + * Used to store the actual width of the source of this texture + * + * @member {number} + * @readOnly + */ this.realWidth = 100; + /** + * Used to store the actual height of the source of this texture + * + * @member {number} + * @readOnly + */ this.realHeight = 100; /** @@ -96,6 +109,7 @@ this.imageUrl = null; /** + * Wether or not the texture is a power of two, try to use power of two textures as much as you can * @member {boolean} * @private */ diff --git a/src/core/textures/RenderTexture.js b/src/core/textures/RenderTexture.js index 137fc02..8958dfc 100644 --- a/src/core/textures/RenderTexture.js +++ b/src/core/textures/RenderTexture.js @@ -360,6 +360,11 @@ }; +/** + * Destroys this texture + * + * @param destroyBase {boolean} Whether to destroy the base texture as well + */ RenderTexture.prototype.destroy = function () { Texture.prototype.destroy.call(this, true); diff --git a/src/core/textures/Texture.js b/src/core/textures/Texture.js index ad7f09c..83bc702 100644 --- a/src/core/textures/Texture.js +++ b/src/core/textures/Texture.js @@ -9,6 +9,14 @@ * A texture stores the information that represents an image or part of an image. It cannot be added * to the display list directly. Instead use it as the texture for a Sprite. If no frame is provided then the whole image is used. * + * You can directly create a texture from an image and then reuse it multiple times like this : + * + * ```js + * var texture = PIXI.Texture.fromImage('assets/image.png'); + * var sprite1 = new PIXI.Sprite(texture); + * var sprite2 = new PIXI.Sprite(texture); + * ``` + * * @class * @mixes eventTarget * @namespace PIXI @@ -16,7 +24,7 @@ * @param [frame] {Rectangle} The rectangle frame of the texture to show * @param [crop] {Rectangle} The area of original texture * @param [trim] {Rectangle} Trimmed texture rectangle - * @param [rotate] {Rectangle} indicates if the texture should be rotated 90 degrees ( used by texture packer ) + * @param [rotate] {boolean} indicates whether the texture should be rotated by 90 degrees ( used by texture packer ) */ function Texture(baseTexture, frame, crop, trim, rotate) { @@ -79,7 +87,7 @@ /** * The WebGL UV data cache. * - * @member {object} + * @member {TextureUvs} * @private */ this._uvs = null; @@ -107,10 +115,10 @@ this.crop = crop || frame;//new math.Rectangle(0, 0, 1, 1); /** - * The rotation value of the texture. + * Indicates whether the texture should be rotated by 90 degrees * * @private - * @member {number} + * @member {boolean} */ this.rotate = !!rotate; @@ -248,7 +256,7 @@ * @param imageUrl {string} The image url of the texture * @param crossorigin {boolean} Whether requests should be treated as crossorigin * @param scaleMode {number} See {{#crossLink "PIXI/scaleModes:property"}}scaleModes{{/crossLink}} for possible values - * @return Texture + * @return {Texture} The newly created texture */ Texture.fromImage = function (imageUrl, crossorigin, scaleMode) { @@ -263,7 +271,14 @@ return texture; }; - +/** + * Helper function that creates a sprite that will contain a texture from the TextureCache based on the frameId + * The frame ids are created when a Texture packer file has been loaded + * + * @static + * @param frameId {String} The frame Id of the texture in the cache + * @return {Texture} The newly created texture + */ Texture.fromFrame = function (frameId) { var texture = utils.TextureCache[frameId]; diff --git a/src/core/textures/TextureUvs.js b/src/core/textures/TextureUvs.js index fd1682f..cdfbbd7 100644 --- a/src/core/textures/TextureUvs.js +++ b/src/core/textures/TextureUvs.js @@ -1,4 +1,9 @@ +/** + * A standard object to store the Uvs of a texture + * + * @class + */ function TextureUvs() { this.x0 = 0; @@ -16,6 +21,13 @@ module.exports = TextureUvs; +/** + * Sets the texture Uvs based on the given frame information + * @param frame {Rectangle} + * @param baseFrame {Rectangle} + * @param rotate {boolean} Whether or not the frame is rotated + * @private + */ TextureUvs.prototype.set = function (frame, baseFrame, rotate) { var tw = baseFrame.width; diff --git a/src/core/textures/VideoBaseTexture.js b/src/core/textures/VideoBaseTexture.js index f6b72c7..319d85c 100644 --- a/src/core/textures/VideoBaseTexture.js +++ b/src/core/textures/VideoBaseTexture.js @@ -4,6 +4,23 @@ /** * A texture of a [playing] Video. * + * Video base textures mimic Pixi BaseTexture.from.... method in their creation process. + * + * This can be used in several ways, such as: + * + * ```js + * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); + * + * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); + * + * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); + * + * var texture = PIXI.VideoBaseTexture.fromUrls([ + * { src: '/video.webm', mime: 'video/webm' }, + * { src: '/video.mp4', mime: 'video/mp4' } + * ]); + * ``` + * * See the ["deus" demo](http://www.goodboydigital.com/pixijs/examples/deus/). * * @class @@ -29,6 +46,12 @@ BaseTexture.call(this, source, scaleMode); + /** + * Should the base texture automatically update itself, set to true by default + * + * @member {boolean} + * @default true + */ this.autoUpdate = false; this._onUpdate = this._onUpdate.bind(this); @@ -51,6 +74,10 @@ VideoBaseTexture.prototype.constructor = VideoBaseTexture; module.exports = VideoBaseTexture; +/** + * The internal update loop of the video base texture, only runs when autoUpdate is set to true + * @private + */ VideoBaseTexture.prototype._onUpdate = function () { if (this.autoUpdate) @@ -60,6 +87,10 @@ } }; +/** + * Runs the update loop when the video is ready to play + * @private + */ VideoBaseTexture.prototype._onPlayStart = function () { if (!this.autoUpdate) @@ -69,11 +100,19 @@ } }; +/** + * Fired when a pause event is triggered, stops the update loop + * @private + */ VideoBaseTexture.prototype._onPlayStop = function () { this.autoUpdate = false; }; +/** + * Fired when the video is loaded and ready to play + * @private + */ VideoBaseTexture.prototype._onCanPlay = function () { this.hasLoaded = true; @@ -97,6 +136,10 @@ } }; +/** + * Destroys this texture + * + */ VideoBaseTexture.prototype.destroy = function () { if (this.source && this.source._pixiId) @@ -138,22 +181,8 @@ }; /** - * Mimic Pixi BaseTexture.from.... method. - * - * This can be used in a couple ways, such as: - * - * ```js - * var texture = PIXI.VideoBaseTexture.fromUrl('http://mydomain.com/video.mp4'); - * - * var texture = PIXI.VideoBaseTexture.fromUrl({ src: 'http://mydomain.com/video.mp4', mime: 'video/mp4' }); - * - * var texture = PIXI.VideoBaseTexture.fromUrls(['/video.webm', '/video.mp4']); - * - * var texture = PIXI.VideoBaseTexture.fromUrls([ - * { src: '/video.webm', mime: 'video/webm' }, - * { src: '/video.mp4', mime: 'video/mp4' } - * ]); - * ``` + * Helper function that creates a new BaseTexture based on the given video element. + * This BaseTexture can then be used to create a texture * * @alias fromUrls * @static diff --git a/src/core/utils/Ticker.js b/src/core/utils/Ticker.js index 9beeddc..1016986 100644 --- a/src/core/utils/Ticker.js +++ b/src/core/utils/Ticker.js @@ -2,14 +2,36 @@ var eventTarget = require('./eventTarget'), EventData = require('./EventData'); +/** + * A Ticker class that runs the main update loop that other objects listen to + * + * @class + * + */ var Ticker = function() { this.updateBind = this.update.bind(this); + /** + * Whether or not this ticker runs + * + * @member {boolean} + */ this.active = false; this.eventData = new EventData( this, 'tick', { deltaTime:1 } ); + /** + * The deltaTime + * + * @member {number} + */ this.deltaTime = 1; + + /** + * The time between two frames + * + * @member {number} + */ this.timeElapsed = 0; this.lastTime = 0; @@ -19,10 +41,9 @@ this.start(); }; - - eventTarget.mixin(Ticker.prototype); + Ticker.prototype.start = function() { if(this.active) diff --git a/src/core/utils/index.js b/src/core/utils/index.js index 8fa3e2f..70eb1ae 100644 --- a/src/core/utils/index.js +++ b/src/core/utils/index.js @@ -138,8 +138,7 @@ * used by spritesheets and image urls * TODO make this smarter! * - * @param width {number} - * @param height {number} + * @param url {string} the image path * @return {boolean} */ getResolutionOfUrl: function (url) diff --git a/src/core/utils/pluginTarget.js b/src/core/utils/pluginTarget.js index 7969d02..3157f89 100644 --- a/src/core/utils/pluginTarget.js +++ b/src/core/utils/pluginTarget.js @@ -13,11 +13,21 @@ { obj.__plugins = {}; + /** + * Adds a plugin to an object + * + * @param pluginName {string} The events that should be listed. + * @param ctor {Object} ?? @alvin + */ obj.registerPlugin = function (pluginName, ctor) { obj.__plugins[pluginName] = ctor; }; + /** + * Instantiates all the plugins of this object + * + */ obj.prototype.initPlugins = function () { this.plugins = this.plugins || {}; @@ -28,6 +38,10 @@ } }; + /** + * Removes all the plugins of this object + * + */ obj.prototype.destroyPlugins = function () { for (var o in this.plugins) diff --git a/src/extras/MovieClip.js b/src/extras/MovieClip.js index a297dcd..b567a29 100644 --- a/src/extras/MovieClip.js +++ b/src/extras/MovieClip.js @@ -92,6 +92,13 @@ } }, + /** + * The array of textures used for this MovieClip + * + * @member + * @memberof MovieClip# + * + */ textures: { get: function () { @@ -148,7 +155,7 @@ this.currentFrame = frameNumber; - var round = Math.round(this.currentFrame); + var round = Math.floor(this.currentFrame); this.texture = this._textures[round % this._textures.length]; }; @@ -165,7 +172,6 @@ /* * Updates the object transform for rendering - * * @private */ MovieClip.prototype.update = function ( event ) diff --git a/src/extras/Rope.js b/src/extras/Rope.js index 47c8f48..8b85d60 100644 --- a/src/extras/Rope.js +++ b/src/extras/Rope.js @@ -6,17 +6,36 @@ * @namespace PIXI * @extends Strip * @param {Texture} texture - The texture to use on the rope. - * @param {Array} points - An array of {Point}. + * @param {Array} points - An array of {Point} objects. * */ function Rope(texture, points) { Strip.call(this, texture); + + /* + * @member {Array} An array of points that determine the rope + */ this.points = points; + /* + * @member {Float32Array} An array of vertices used to construct this rope. + */ this.vertices = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} The WebGL Uvs of the rope. + */ this.uvs = new Float32Array(points.length * 4); + + /* + * @member {Float32Array} An array containing the color components + */ this.colors = new Float32Array(points.length * 2); + + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array(points.length * 2); this.refresh(); diff --git a/src/extras/Strip.js b/src/extras/Strip.js index a6fa179..519821f 100644 --- a/src/extras/Strip.js +++ b/src/extras/Strip.js @@ -21,19 +21,36 @@ */ this.texture = texture; - // set up the main bits.. + /** + * The Uvs of the strip + * + * @member {Float32Array} + */ this.uvs = new Float32Array([0, 1, 1, 1, 1, 0, 0, 1]); + /** + * An array of vertices + * + * @member {Float32Array} + */ this.vertices = new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]); + /** + * The color components + * + * @member {Float32Array} + */ this.colors = new Float32Array([1, 1, 1, 1]); + /* + * @member {Uint16Array} An array containing the indices of the vertices + */ this.indices = new Uint16Array([0, 1, 2, 3]); /** @@ -58,6 +75,11 @@ */ this.canvasPadding = 0; + /** + * The way the strip should be drawn, can be any of the Strip.DrawModes consts + * + * @member {number} + */ this.drawMode = Strip.DrawModes.TRIANGLE_STRIP; } @@ -69,7 +91,7 @@ /** * Renders the object using the WebGL renderer * - * @param renderer {WebGLRenderer} + * @param renderer {WebGLRenderer} a reference to the WebGL renderer */ Strip.prototype.renderWebGL = function (renderer) { @@ -100,6 +122,12 @@ //TODO check culling }; +/** + * Creates the buffers and (in the darkness) binds them + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._initWebGL = function (renderer) { // build the strip! @@ -123,6 +151,12 @@ gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, this.indices, gl.STATIC_DRAW); }; +/** + * Renders the strip ! + * + * @param renderer {WebGLRenderer} a reference to the WebGL renderer + * @private + */ Strip.prototype._renderStrip = function (renderer) { var gl = renderer.gl; @@ -246,6 +280,12 @@ } }; +/** + * Draws the object in TRIANGLE_STRIP mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangleStrip = function (context) { // draw triangles!! @@ -263,6 +303,12 @@ } }; +/** + * Draws the object in triangle mode using canvas + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @private + */ Strip.prototype._renderCanvasTriangles = function (context) { // draw triangles!! @@ -281,6 +327,17 @@ } }; +/** + * Draws one of the triangles that form this strip + * + * @param context {CanvasRenderingContext2D} the current drawing context + * @param vertices {Float32Array} a reference to the the vertices of the strip + * @param uvs {Float32Array} a reference to the the vertices of the strip + * @param index0 {number} the index of the first vertex + * @param index1 {number} the index of the second vertex + * @param index2 {number} the index of the third vertex + * @private + */ Strip.prototype._renderCanvasDrawTriangle = function (context, vertices, uvs, index0, index1, index2) { var textureSource = this.texture.baseTexture.source; diff --git a/src/extras/StripShader.js b/src/extras/StripShader.js index bb12757..acbe147 100644 --- a/src/extras/StripShader.js +++ b/src/extras/StripShader.js @@ -3,7 +3,8 @@ /** * @class * @namespace PIXI - * @param shaderManager {ShaderManager} The webgl shader manager this shader works for. + * @param shaderManager {ShaderManager} The WebGL shader manager this shader works for. + * @extends Shader */ function StripShader(shaderManager) { diff --git a/src/extras/TilingSprite.js b/src/extras/TilingSprite.js index 18955c0..bbd1f56 100644 --- a/src/extras/TilingSprite.js +++ b/src/extras/TilingSprite.js @@ -19,8 +19,6 @@ { core.Sprite.call(this, texture); - - /** * The scaling of the image that is being tiled * @@ -36,14 +34,13 @@ */ this.tilePosition = new core.math.Point(0,0); - - ///// private /** * The with of the tiling sprite * * @member {number} + * @private */ this._width = width || 100; @@ -51,6 +48,7 @@ * The height of the tiling sprite * * @member {number} + * @private */ this._height = height || 100; @@ -58,13 +56,33 @@ * A point that represents the scale of the texture object * * @member {Point} + * @private */ this._tileScaleOffset = new core.math.Point(1,1); + /** + * + * + * @member {boolean} + * @private + */ this._tilingTexture = null; + + /** + * + * + * @member {boolean} + * @private + */ this._refreshTexture = false; + /** + * An internal WebGL UV cache. + * + * @member {TextureUvs} + * @private + */ this._uvs = new TextureUvs(); } @@ -187,7 +205,7 @@ /** * Renders the object using the Canvas renderer * - * @param renderer {CanvasRenderer} + * @param renderer {CanvasRenderer} a reference to the canvas renderer */ TilingSprite.prototype.renderCanvas = function (renderer) { @@ -359,7 +377,9 @@ }; /** - * + * Creates the tiling texture + * @param renderer {CanvasRenderer|WebGLRenderer} a reference to the current renderer + * @param texture {Texture} The texture to use to generate the tiling texture * @param forcePowerOfTwo {boolean} Whether we want to force the texture to be a power of two */ TilingSprite.prototype.generateTilingTexture = function (renderer, texture, forcePowerOfTwo) @@ -421,6 +441,10 @@ }; +/** + * Checks if a point is inside this tiling sprite + * @param point {Point} the point to check + */ TilingSprite.prototype.hitTest = function( point ) { this.worldTransform.applyInverse(point, tempPoint); @@ -443,7 +467,10 @@ return false; }; - +/** + * Destroys this tiling sprite + * + */ TilingSprite.prototype.destroy = function () { core.Sprite.prototype.destroy.call(this); diff --git a/src/interaction/InteractionManager.js b/src/interaction/InteractionManager.js index 1270b14..ad7001a 100644 --- a/src/interaction/InteractionManager.js +++ b/src/interaction/InteractionManager.js @@ -13,7 +13,7 @@ * * @class * @namespace PIXI - * @param stage {Stage} The stage to handle interactions + * @param renderer {CanvasRenderer|WebGLRenderer} A reference to the current renderer */ function InteractionManager( renderer ) { @@ -26,6 +26,11 @@ */ this.mouse = new InteractionData(); + /** + * An event data object to handle all the event tracking/dispatching + * + * @member {EventData} + */ this.eventData = new core.utils.EventData(); this.eventData.data = this.mouse; @@ -109,9 +114,15 @@ */ this.currentCursorStyle = 'inherit'; + /** + * Internal cached var + * @member {Point} + * @private + */ this._tempPoint = new core.math.Point(); /** + * The current resolution * @member {number} */ this.resolution = 1; @@ -145,7 +156,7 @@ }; /** - * + * Registers all the DOM events * @private */ InteractionManager.prototype.addEvents = function () @@ -175,7 +186,7 @@ }; /** - * + * Removes all the DOM events that were previously registered * @private */ InteractionManager.prototype.removeEvents = function () @@ -240,7 +251,13 @@ //TODO }; - +/** + * Dispatches an event on the display object that was interacted with + * @param displayObject {Container|Sprite|TilingSprite} the display object in question + * @param eventString {string} the name of the event (e.g, mousedown) + * @param eventData {EventData} the event data object + * @private + */ InteractionManager.prototype.dispatchEvent = function ( displayObject, eventString, eventData ) { if(!eventData.stopped) @@ -257,6 +274,10 @@ } }; +/** + * Ensures the interaction checks don't happen too often by delaying the update loop + * @private + */ InteractionManager.prototype.throttleUpdate = function () { // frequency of 30fps?? @@ -275,10 +296,11 @@ /** * Maps x and y coords from a DOM object and maps them correctly to the pixi view. The resulting value is stored in the point. - * This takes into account the fact that the DOM element could be scaled and position anywhere on the screen. - * @param {[type]} point The point that the result will be stored in - * @param {[type]} x the x coord of the position to map - * @param {[type]} y the y coord of the position to map + * This takes into account the fact that the DOM element could be scaled and positioned anywhere on the screen. + * + * @param {Point} point the point that the result will be stored in + * @param {number} x the x coord of the position to map + * @param {number} y the y coord of the position to map */ InteractionManager.prototype.mapPositionToPoint = function ( point, x, y ) { @@ -290,8 +312,9 @@ /** * This function is provides a neat way of crawling through the scene graph and running a specified function on all interactive objects it finds. * It will also take care of hit testing the interactive objects and passes the hit across in the function. + * * @param {Point} point the point that is tested for collision - * @param {DisplayObject} displayObject the displayObject that will be hit test (recurcsivly crawls its children) + * @param {Container|Sprite|TilingSprite} displayObject the displayObject that will be hit test (recurcsivly crawls its children) * @param {function} func the function that will be called on each interactive object. The displayObject and hit will be passed to the function * @param {boolean} hitTest this indicates if the objects inside should be hit test against the point * @return {boolean} returns true if the displayObject hit the point @@ -376,6 +399,13 @@ this.processInteractive(this.mouse.global, this.renderer._lastObjectRendered, this.processMouseDown, true ); }; +/** + * Processes the result of the mouse down check and dispatches the event if need be + * + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the dispay object + * @private + */ InteractionManager.prototype.processMouseDown = function ( displayObject, hit ) { var e = this.mouse.originalEvent; @@ -406,6 +436,13 @@ this.processInteractive(this.mouse.global, this.renderer._lastObjectRendered, this.processMouseUp, true ); }; +/** + * Processes the result of the mouse up check and dispatches the event if need be + * + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the display object + * @private + */ InteractionManager.prototype.processMouseUp = function ( displayObject, hit ) { var e = this.mouse.originalEvent; @@ -434,8 +471,6 @@ }; - - /** * Is called when the mouse moves across the renderer element * @@ -465,6 +500,13 @@ //TODO BUG for parents ineractive object (border order issue) }; +/** + * Processes the result of the mouse move check and dispatches the event if need be + * + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the display object + * @private + */ InteractionManager.prototype.processMouseMove = function ( displayObject, hit ) { this.dispatchEvent( displayObject, 'mousemove', this.eventData); @@ -491,6 +533,13 @@ this.processInteractive( this.mouse.global, this.renderer._lastObjectRendered, this.processMouseOverOut, false ); }; +/** + * Processes the result of the mouse over/out check and dispatches the event if need be + * + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the display object + * @private + */ InteractionManager.prototype.processMouseOverOut = function ( displayObject, hit ) { if(hit) @@ -549,11 +598,11 @@ } }; - /** - * Is called when a touch is ended on the renderer element + * Processes the result of a touch check and dispatches the event if need be * - * @param event {Event} The DOM event of a touch ending on the renderer view + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the display object * @private */ InteractionManager.prototype.processTouchStart = function ( displayObject, hit ) @@ -570,7 +619,7 @@ /** * [onTouchEnd description] * @param {[type]} event [description] - * @return {[type]} [description] + * */ InteractionManager.prototype.onTouchEnd = function (event) { @@ -600,6 +649,13 @@ } }; +/** + * Processes the result of the end of a touch and dispatches the event if need be + * + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the display object + * @private + */ InteractionManager.prototype.processTouchEnd = function ( displayObject, hit ) { if(hit) @@ -654,14 +710,26 @@ } }; - +/** + * Processes the result of a touch move check and dispatches the event if need be + * + * @param displayObject {Container|Sprite|TilingSprite} The display object that was tested + * @param hit {boolean} the result of the hit test on the display object + * @private + */ InteractionManager.prototype.processTouchMove = function ( displayObject, hit ) { hit = hit; this.dispatchEvent( displayObject, 'touchmove', this.eventData); }; - +/** + * Grabs an interaction data object from the internal pool + * + * @param touchEvent {} The touch event we need to pair with a touchData object + * + * @private + */ InteractionManager.prototype.getTouchData = function (touchEvent) { var touchData = this.interactiveDataPool.pop(); @@ -677,6 +745,13 @@ return touchData; }; +/** + * Returns an interaction data object to the internal pool + * + * @param touchEvent {InteractionData} The touch data object we want to return to the pool + * + * @private + */ InteractionManager.prototype.returnTouchData = function ( touchData ) { this.interactiveDataPool.push( touchData );