diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/mask/StencilSystem.js b/packages/core/src/mask/StencilSystem.js index 122c5d1..bf9ddae 100644 --- a/packages/core/src/mask/StencilSystem.js +++ b/packages/core/src/mask/StencilSystem.js @@ -13,6 +13,11 @@ constructor(renderer) { super(renderer); + + /** + * The mask stack + * @member {PIXI.Graphics[]} + */ this.stencilMaskStack = []; } @@ -102,6 +107,7 @@ /** * Setup renderer to use the current stencil data. + * @private */ _useCurrent() { @@ -114,7 +120,7 @@ /** * Fill 1s equal to the number of acitve stencil masks. - * + * @private * @return {number} The bitwise mask. */ _getBitwiseMask() diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/mask/StencilSystem.js b/packages/core/src/mask/StencilSystem.js index 122c5d1..bf9ddae 100644 --- a/packages/core/src/mask/StencilSystem.js +++ b/packages/core/src/mask/StencilSystem.js @@ -13,6 +13,11 @@ constructor(renderer) { super(renderer); + + /** + * The mask stack + * @member {PIXI.Graphics[]} + */ this.stencilMaskStack = []; } @@ -102,6 +107,7 @@ /** * Setup renderer to use the current stencil data. + * @private */ _useCurrent() { @@ -114,7 +120,7 @@ /** * Fill 1s equal to the number of acitve stencil masks. - * + * @private * @return {number} The bitwise mask. */ _getBitwiseMask() diff --git a/packages/core/src/projection/ProjectionSystem.js b/packages/core/src/projection/ProjectionSystem.js index 6e63b73..b953079 100644 --- a/packages/core/src/projection/ProjectionSystem.js +++ b/packages/core/src/projection/ProjectionSystem.js @@ -16,9 +16,43 @@ { super(renderer); + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.destinationFrame = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.sourceFrame = null; + + /** + * Default destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.defaultFrame = null; + + /** + * Project matrix + * @member {PIXI.Matrix} + * @readonly + */ this.projectionMatrix = new Matrix(); } + /** + * Updates the projection matrix based on a projection frame (which is a rectangle) + * + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root + */ update(destinationFrame, sourceFrame, resolution, root) { this.destinationFrame = destinationFrame || this.destinationFrame || this.defaultFrame; @@ -33,8 +67,10 @@ /** * Updates the projection matrix based on a projection frame (which is a rectangle) * - * @param {Rectangle} destinationFrame - The destination frame. - * @param {Rectangle} sourceFrame - The source frame. + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root */ calculateProjection(destinationFrame, sourceFrame, resolution, root) { diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/mask/StencilSystem.js b/packages/core/src/mask/StencilSystem.js index 122c5d1..bf9ddae 100644 --- a/packages/core/src/mask/StencilSystem.js +++ b/packages/core/src/mask/StencilSystem.js @@ -13,6 +13,11 @@ constructor(renderer) { super(renderer); + + /** + * The mask stack + * @member {PIXI.Graphics[]} + */ this.stencilMaskStack = []; } @@ -102,6 +107,7 @@ /** * Setup renderer to use the current stencil data. + * @private */ _useCurrent() { @@ -114,7 +120,7 @@ /** * Fill 1s equal to the number of acitve stencil masks. - * + * @private * @return {number} The bitwise mask. */ _getBitwiseMask() diff --git a/packages/core/src/projection/ProjectionSystem.js b/packages/core/src/projection/ProjectionSystem.js index 6e63b73..b953079 100644 --- a/packages/core/src/projection/ProjectionSystem.js +++ b/packages/core/src/projection/ProjectionSystem.js @@ -16,9 +16,43 @@ { super(renderer); + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.destinationFrame = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.sourceFrame = null; + + /** + * Default destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.defaultFrame = null; + + /** + * Project matrix + * @member {PIXI.Matrix} + * @readonly + */ this.projectionMatrix = new Matrix(); } + /** + * Updates the projection matrix based on a projection frame (which is a rectangle) + * + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root + */ update(destinationFrame, sourceFrame, resolution, root) { this.destinationFrame = destinationFrame || this.destinationFrame || this.defaultFrame; @@ -33,8 +67,10 @@ /** * Updates the projection matrix based on a projection frame (which is a rectangle) * - * @param {Rectangle} destinationFrame - The destination frame. - * @param {Rectangle} sourceFrame - The source frame. + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root */ calculateProjection(destinationFrame, sourceFrame, resolution, root) { diff --git a/packages/core/src/renderTexture/RenderTextureSystem.js b/packages/core/src/renderTexture/RenderTextureSystem.js index 3b7bcf0..46349b5 100644 --- a/packages/core/src/renderTexture/RenderTextureSystem.js +++ b/packages/core/src/renderTexture/RenderTextureSystem.js @@ -18,18 +18,50 @@ { super(renderer); + /** + * The clear background color as rgba + * @member {number[]} + */ this.clearColor = renderer._backgroundColorRgba; - // TODO moe this property somewhere else! + // TODO move this property somewhere else! + /** + * List of masks for the StencilSystem + * @member {Array} + * @readonly + */ this.defaultMaskStack = []; + + /** + * List of filters for the FilterSystem + * @member {Array} + * @readonly + */ this.defaultFilterStack = [{}]; // empty render texture? + /** + * Render texture + * @member {PIXI.RenderTexture} + * @readonly + */ this.renderTexture = null; + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ this.destinationFrame = new Rectangle(); } + /** + * Bind the current render texture + * @private + * @param {PIXI.RenderTexture} renderTexture + * @param {PIXI.Rectangle} sourceFrame + * @param {PIXI.Rectangle} destinationFrame + */ bind(renderTexture, sourceFrame, destinationFrame) { // TODO - do we want this?? @@ -100,7 +132,7 @@ /** * Erases the render texture and fills the drawing area with a colour * - * @param {number} [clearColor] - The colour + * @param {number[]} [clearColor] - The color as rgba, default to use the renderer backgroundColor * @return {PIXI.Renderer} Returns itself. */ clear(clearColor) diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/mask/StencilSystem.js b/packages/core/src/mask/StencilSystem.js index 122c5d1..bf9ddae 100644 --- a/packages/core/src/mask/StencilSystem.js +++ b/packages/core/src/mask/StencilSystem.js @@ -13,6 +13,11 @@ constructor(renderer) { super(renderer); + + /** + * The mask stack + * @member {PIXI.Graphics[]} + */ this.stencilMaskStack = []; } @@ -102,6 +107,7 @@ /** * Setup renderer to use the current stencil data. + * @private */ _useCurrent() { @@ -114,7 +120,7 @@ /** * Fill 1s equal to the number of acitve stencil masks. - * + * @private * @return {number} The bitwise mask. */ _getBitwiseMask() diff --git a/packages/core/src/projection/ProjectionSystem.js b/packages/core/src/projection/ProjectionSystem.js index 6e63b73..b953079 100644 --- a/packages/core/src/projection/ProjectionSystem.js +++ b/packages/core/src/projection/ProjectionSystem.js @@ -16,9 +16,43 @@ { super(renderer); + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.destinationFrame = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.sourceFrame = null; + + /** + * Default destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.defaultFrame = null; + + /** + * Project matrix + * @member {PIXI.Matrix} + * @readonly + */ this.projectionMatrix = new Matrix(); } + /** + * Updates the projection matrix based on a projection frame (which is a rectangle) + * + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root + */ update(destinationFrame, sourceFrame, resolution, root) { this.destinationFrame = destinationFrame || this.destinationFrame || this.defaultFrame; @@ -33,8 +67,10 @@ /** * Updates the projection matrix based on a projection frame (which is a rectangle) * - * @param {Rectangle} destinationFrame - The destination frame. - * @param {Rectangle} sourceFrame - The source frame. + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root */ calculateProjection(destinationFrame, sourceFrame, resolution, root) { diff --git a/packages/core/src/renderTexture/RenderTextureSystem.js b/packages/core/src/renderTexture/RenderTextureSystem.js index 3b7bcf0..46349b5 100644 --- a/packages/core/src/renderTexture/RenderTextureSystem.js +++ b/packages/core/src/renderTexture/RenderTextureSystem.js @@ -18,18 +18,50 @@ { super(renderer); + /** + * The clear background color as rgba + * @member {number[]} + */ this.clearColor = renderer._backgroundColorRgba; - // TODO moe this property somewhere else! + // TODO move this property somewhere else! + /** + * List of masks for the StencilSystem + * @member {Array} + * @readonly + */ this.defaultMaskStack = []; + + /** + * List of filters for the FilterSystem + * @member {Array} + * @readonly + */ this.defaultFilterStack = [{}]; // empty render texture? + /** + * Render texture + * @member {PIXI.RenderTexture} + * @readonly + */ this.renderTexture = null; + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ this.destinationFrame = new Rectangle(); } + /** + * Bind the current render texture + * @private + * @param {PIXI.RenderTexture} renderTexture + * @param {PIXI.Rectangle} sourceFrame + * @param {PIXI.Rectangle} destinationFrame + */ bind(renderTexture, sourceFrame, destinationFrame) { // TODO - do we want this?? @@ -100,7 +132,7 @@ /** * Erases the render texture and fills the drawing area with a colour * - * @param {number} [clearColor] - The colour + * @param {number[]} [clearColor] - The color as rgba, default to use the renderer backgroundColor * @return {PIXI.Renderer} Returns itself. */ clear(clearColor) diff --git a/packages/core/src/state/StateSystem.js b/packages/core/src/state/StateSystem.js index df4044a..a29d215 100755 --- a/packages/core/src/state/StateSystem.js +++ b/packages/core/src/state/StateSystem.js @@ -1,6 +1,6 @@ import mapWebGLBlendModesToPixi from './utils/mapWebGLBlendModesToPixi'; import System from '../System'; -import WebGLState from './State'; +import State from './State'; const BLEND = 0; const OFFSET = 1; @@ -12,31 +12,75 @@ * A WebGL state machines * * @class - * @extends PIXI.systems.System + * @extends PIXI.System * @memberof PIXI.systems */ export default class StateSystem extends System { /** - * @param {WebGLRenderingContext} gl - The current WebGL rendering context + * @param {PIXI.Renderer} renderer - Reference to renderer */ constructor(renderer) { super(renderer); + /** + * GL context + * @member {WebGLRenderingContext} + * @readonly + */ this.gl = null; + /** + * Return from MAX_VERTEX_ATTRIBS + * @member {number} + * @readonly + */ this.maxAttribs = null; - // check we have vao.. + /** + * Check we have vao + * @member {OES_vertex_array_object} + * @readonly + */ this.nativeVaoExtension = null; + /** + * Attribute state + * @member {object} + * @readonly + * @property {Array} tempAttribState + * @property {Array} attribState + */ this.attribState = null; + /** + * State ID + * @member {number} + * @readonly + */ this.stateId = 0; + + /** + * Polygon offset + * @member {number} + * @readonly + */ this.polygonOffset = 0; + + /** + * Blend mode + * @member {number} + * @default 17 + * @readonly + */ this.blendMode = 17; + /** + * Collection of calls + * @member {function[]} + * @readonly + */ this.map = []; // map functions for when we set state.. @@ -46,20 +90,25 @@ this.map[DEPTH_TEST] = this.setDepthTest; this.map[WINDING] = this.setFrontFace; + /** + * Collection of check calls + * @member {function[]} + * @readonly + */ this.checks = []; - this.defaultState = new WebGLState(); + /** + * Default WebGL State + * @member {PIXI.State} + * @readonly + */ + this.defaultState = new State(); this.defaultState.blend = true; this.defaultState.depth = true; } contextChange(gl) { - /** - * The current WebGL rendering context - * - * @member {WebGLRenderingContext} - */ this.gl = gl; this.maxAttribs = gl.getParameter(gl.MAX_VERTEX_ATTRIBS); diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/mask/StencilSystem.js b/packages/core/src/mask/StencilSystem.js index 122c5d1..bf9ddae 100644 --- a/packages/core/src/mask/StencilSystem.js +++ b/packages/core/src/mask/StencilSystem.js @@ -13,6 +13,11 @@ constructor(renderer) { super(renderer); + + /** + * The mask stack + * @member {PIXI.Graphics[]} + */ this.stencilMaskStack = []; } @@ -102,6 +107,7 @@ /** * Setup renderer to use the current stencil data. + * @private */ _useCurrent() { @@ -114,7 +120,7 @@ /** * Fill 1s equal to the number of acitve stencil masks. - * + * @private * @return {number} The bitwise mask. */ _getBitwiseMask() diff --git a/packages/core/src/projection/ProjectionSystem.js b/packages/core/src/projection/ProjectionSystem.js index 6e63b73..b953079 100644 --- a/packages/core/src/projection/ProjectionSystem.js +++ b/packages/core/src/projection/ProjectionSystem.js @@ -16,9 +16,43 @@ { super(renderer); + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.destinationFrame = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.sourceFrame = null; + + /** + * Default destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.defaultFrame = null; + + /** + * Project matrix + * @member {PIXI.Matrix} + * @readonly + */ this.projectionMatrix = new Matrix(); } + /** + * Updates the projection matrix based on a projection frame (which is a rectangle) + * + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root + */ update(destinationFrame, sourceFrame, resolution, root) { this.destinationFrame = destinationFrame || this.destinationFrame || this.defaultFrame; @@ -33,8 +67,10 @@ /** * Updates the projection matrix based on a projection frame (which is a rectangle) * - * @param {Rectangle} destinationFrame - The destination frame. - * @param {Rectangle} sourceFrame - The source frame. + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root */ calculateProjection(destinationFrame, sourceFrame, resolution, root) { diff --git a/packages/core/src/renderTexture/RenderTextureSystem.js b/packages/core/src/renderTexture/RenderTextureSystem.js index 3b7bcf0..46349b5 100644 --- a/packages/core/src/renderTexture/RenderTextureSystem.js +++ b/packages/core/src/renderTexture/RenderTextureSystem.js @@ -18,18 +18,50 @@ { super(renderer); + /** + * The clear background color as rgba + * @member {number[]} + */ this.clearColor = renderer._backgroundColorRgba; - // TODO moe this property somewhere else! + // TODO move this property somewhere else! + /** + * List of masks for the StencilSystem + * @member {Array} + * @readonly + */ this.defaultMaskStack = []; + + /** + * List of filters for the FilterSystem + * @member {Array} + * @readonly + */ this.defaultFilterStack = [{}]; // empty render texture? + /** + * Render texture + * @member {PIXI.RenderTexture} + * @readonly + */ this.renderTexture = null; + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ this.destinationFrame = new Rectangle(); } + /** + * Bind the current render texture + * @private + * @param {PIXI.RenderTexture} renderTexture + * @param {PIXI.Rectangle} sourceFrame + * @param {PIXI.Rectangle} destinationFrame + */ bind(renderTexture, sourceFrame, destinationFrame) { // TODO - do we want this?? @@ -100,7 +132,7 @@ /** * Erases the render texture and fills the drawing area with a colour * - * @param {number} [clearColor] - The colour + * @param {number[]} [clearColor] - The color as rgba, default to use the renderer backgroundColor * @return {PIXI.Renderer} Returns itself. */ clear(clearColor) diff --git a/packages/core/src/state/StateSystem.js b/packages/core/src/state/StateSystem.js index df4044a..a29d215 100755 --- a/packages/core/src/state/StateSystem.js +++ b/packages/core/src/state/StateSystem.js @@ -1,6 +1,6 @@ import mapWebGLBlendModesToPixi from './utils/mapWebGLBlendModesToPixi'; import System from '../System'; -import WebGLState from './State'; +import State from './State'; const BLEND = 0; const OFFSET = 1; @@ -12,31 +12,75 @@ * A WebGL state machines * * @class - * @extends PIXI.systems.System + * @extends PIXI.System * @memberof PIXI.systems */ export default class StateSystem extends System { /** - * @param {WebGLRenderingContext} gl - The current WebGL rendering context + * @param {PIXI.Renderer} renderer - Reference to renderer */ constructor(renderer) { super(renderer); + /** + * GL context + * @member {WebGLRenderingContext} + * @readonly + */ this.gl = null; + /** + * Return from MAX_VERTEX_ATTRIBS + * @member {number} + * @readonly + */ this.maxAttribs = null; - // check we have vao.. + /** + * Check we have vao + * @member {OES_vertex_array_object} + * @readonly + */ this.nativeVaoExtension = null; + /** + * Attribute state + * @member {object} + * @readonly + * @property {Array} tempAttribState + * @property {Array} attribState + */ this.attribState = null; + /** + * State ID + * @member {number} + * @readonly + */ this.stateId = 0; + + /** + * Polygon offset + * @member {number} + * @readonly + */ this.polygonOffset = 0; + + /** + * Blend mode + * @member {number} + * @default 17 + * @readonly + */ this.blendMode = 17; + /** + * Collection of calls + * @member {function[]} + * @readonly + */ this.map = []; // map functions for when we set state.. @@ -46,20 +90,25 @@ this.map[DEPTH_TEST] = this.setDepthTest; this.map[WINDING] = this.setFrontFace; + /** + * Collection of check calls + * @member {function[]} + * @readonly + */ this.checks = []; - this.defaultState = new WebGLState(); + /** + * Default WebGL State + * @member {PIXI.State} + * @readonly + */ + this.defaultState = new State(); this.defaultState.blend = true; this.defaultState.depth = true; } contextChange(gl) { - /** - * The current WebGL rendering context - * - * @member {WebGLRenderingContext} - */ this.gl = gl; this.maxAttribs = gl.getParameter(gl.MAX_VERTEX_ATTRIBS); diff --git a/packages/core/src/textures/TextureGCSystem.js b/packages/core/src/textures/TextureGCSystem.js index 6d07606..90477ce 100644 --- a/packages/core/src/textures/TextureGCSystem.js +++ b/packages/core/src/textures/TextureGCSystem.js @@ -19,10 +19,39 @@ { super(renderer); + /** + * Count + * @member {number} + * @readonly + */ this.count = 0; + + /** + * Check count + * @member {number} + * @readonly + */ this.checkCount = 0; + + /** + * Maximum idle time, in seconds + * @member {number} + * @see PIXI.settings.GC_MAX_IDLE + */ this.maxIdle = settings.GC_MAX_IDLE; + + /** + * Maximum number of itesm to check + * @member {number} + * @see PIXI.settings.GC_MAX_CHECK_COUNT + */ this.checkCountMax = settings.GC_MAX_CHECK_COUNT; + + /** + * Current garabage collection mode + * @member {PIXI.GC_MODES} + * @see PIXI.settings.GC_MODE + */ this.mode = settings.GC_MODE; } diff --git a/packages/core/src/Renderer.js b/packages/core/src/Renderer.js index 935d455..5e698f2 100644 --- a/packages/core/src/Renderer.js +++ b/packages/core/src/Renderer.js @@ -76,33 +76,129 @@ // TODO legacy! - // runners! + /** + * Internal signal instances of **mini-runner**, these + * are assigned to each system created. + * @see https://github.com/GoodBoyDigital/mini-runner + * @name PIXI.Renderer#runners + * @type {object} + * @readonly + * @property {Runner} destroy - Destroy runner + * @property {Runner} contextChange - Context change runner + * @property {Runner} reset - Reset runner + * @property {Runner} update - Update runner + * @property {Runner} postrender - Post-render runner + * @property {Runner} prerender - Pre-render runner + * @property {Runner} resize - Resize runner + */ this.runners = { - destroy: new Runner('destroy'), - contextChange: new Runner('contextChange', 1), - reset: new Runner('reset'), - update: new Runner('update'), - postrender: new Runner('postrender'), - prerender: new Runner('prerender'), - resize: new Runner('resize', 2), + destroy: new Runner('destroy'), + contextChange: new Runner('contextChange', 1), + reset: new Runner('reset'), + update: new Runner('update'), + postrender: new Runner('postrender'), + prerender: new Runner('prerender'), + resize: new Runner('resize', 2), }; + /** + * Global uniforms + * @member {PIXI.UniformGroup} + */ this.globalUniforms = new UniformGroup({ projectionMatrix: new Matrix(), }, true); + /** + * Mask system instance + * @member {PIXI.systems.MaskSystem} mask + * @memberof PIXI.Renderer# + * @readonly + */ this.addSystem(MaskSystem, 'mask') + /** + * Context system instance + * @member {PIXI.systems.ContextSystem} context + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ContextSystem, 'context') + /** + * State system instance + * @member {PIXI.systems.StateSystem} state + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StateSystem, 'state') + /** + * Shader system instance + * @member {PIXI.systems.ShaderSystem} shader + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ShaderSystem, 'shader') + /** + * Texture system instance + * @member {PIXI.systems.TextureSystem} texture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureSystem, 'texture') + /** + * Geometry system instance + * @member {PIXI.systems.GeometrySystem} geometry + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(GeometrySystem, 'geometry') + /** + * Framebuffer system instance + * @member {PIXI.systems.FramebufferSystem} framebuffer + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FramebufferSystem, 'framebuffer') + /** + * Stencil system instance + * @member {PIXI.systems.StencilSystem} stencil + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(StencilSystem, 'stencil') + /** + * Projection system instance + * @member {PIXI.systems.ProjectionSystem} projection + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(ProjectionSystem, 'projection') + /** + * Texture garbage collector system instance + * @member {PIXI.systems.TextureGCSystem} textureGC + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(TextureGCSystem, 'textureGC') + /** + * Filter system instance + * @member {PIXI.systems.FilterSystem} filter + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(FilterSystem, 'filter') + /** + * RenderTexture system instance + * @member {PIXI.systems.RenderTextureSystem} renderTexture + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(RenderTextureSystem, 'renderTexture') + /** + * Batch system instance + * @member {PIXI.systems.BatchSystem} batch + * @memberof PIXI.Renderer# + * @readonly + */ .addSystem(BatchSystem, 'batch'); this.initPlugins(Renderer.__plugins); @@ -129,6 +225,12 @@ }); } + /** + * Flag if we are rendering to the screen vs renderTexture + * @member {boolean} + * @readonly + * @default true + */ this.renderingToScreen = true; sayHello(this.context.webGLVersion === 2 ? 'WebGL 2' : 'WebGL 1'); @@ -152,21 +254,11 @@ name = ClassRef.name; } - // TODO - read name from class.name.. - - /* - if(name.includes('System')) - { - name = name.replace('System', ''); - name = name.charAt(0).toLowerCase() + name.slice(1); - } - */ - const system = new ClassRef(this); if (this[name]) { - throw new Error(`Whoops! ${name} is already a manger`); + throw new Error(`Whoops! The name "${name}" is already in use`); } this[name] = system; @@ -285,6 +377,9 @@ return this; } + /** + * Clear the frame buffer + */ clear() { this.framebuffer.bind(); diff --git a/packages/core/src/System.js b/packages/core/src/System.js index 05a10c8..0fb494c 100644 --- a/packages/core/src/System.js +++ b/packages/core/src/System.js @@ -23,7 +23,7 @@ /** * Generic method called when there is a WebGL context change. - * + * @param {WebGLRenderingContext} gl - WebGL context */ contextChange() { diff --git a/packages/core/src/batch/BatchSystem.js b/packages/core/src/batch/BatchSystem.js index b04c249..bae087d 100644 --- a/packages/core/src/batch/BatchSystem.js +++ b/packages/core/src/batch/BatchSystem.js @@ -6,7 +6,6 @@ * @extends PIXI.System * @memberof PIXI.systems */ - export default class BatchSystem extends System { /** diff --git a/packages/core/src/context/ContextSystem.js b/packages/core/src/context/ContextSystem.js index a32b5cf..2542fa6 100644 --- a/packages/core/src/context/ContextSystem.js +++ b/packages/core/src/context/ContextSystem.js @@ -18,22 +18,46 @@ { super(renderer); + /** + * Either 1 or 2 to reflect the WebGL version being used + * @member {number} + * @readonly + */ this.webGLVersion = 1; + /** + * Extensions being used + * @name {object} + * @readonly + * @property {WEBGL_draw_buffers} drawBuffers - WebGL v1 extension + * @property {WEBKIT_WEBGL_depth_texture} depthTexture - WebGL v1 extension + * @property {OES_texture_float} floatTexture - WebGL v1 extension + * @property {WEBGL_lose_context} loseContext - WebGL v1 extension + * @property {OES_vertex_array_object} vertexArrayObject - WebGL v1 extension + */ + this.extensions = {}; + + // Bind functions this.handleContextLost = this.handleContextLost.bind(this); this.handleContextRestored = this.handleContextRestored.bind(this); - this.extensions = {}; - renderer.view.addEventListener('webglcontextlost', this.handleContextLost, false); renderer.view.addEventListener('webglcontextrestored', this.handleContextRestored, false); } + /** + * `true` if the context is lost + * @member {boolean} + * @readonly + */ get isLost() { return (!this.gl || this.gl.isContextLost()); } + /** + * Handle the context change event + */ contextChange(gl) { this.gl = gl; @@ -45,6 +69,12 @@ } } + /** + * Initialize the context + * + * @private + * @param {WebGLRenderingContext} gl - WebGL context + */ initFromContext(gl) { this.gl = gl; @@ -54,6 +84,13 @@ this.renderer.runners.contextChange.run(gl); } + /** + * Initialize from context options + * + * @private + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext + * @param {object} options - context attributes + */ initFromOptions(options) { const gl = this.createContext(this.renderer.view, options); @@ -64,11 +101,9 @@ /** * Helper class to create a webGL Context * - * @class - * @memberof PIXI.glCore * @param canvas {HTMLCanvasElement} the canvas element that we will get the context from - * @param options {Object} An options object that gets passed in to the canvas element containing the context attributes, - * see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext for the options available + * @param options {object} An options object that gets passed in to the canvas element containing the context attributes + * @see https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext * @return {WebGLRenderingContext} the WebGL context */ createContext(canvas, options) @@ -105,22 +140,27 @@ return gl; } + /** + * Auto-populate the extensions + * + * @private + */ getExtensions() { // time to set up default extensions that pixi uses.. - const gl = this.gl; - const extensions = this.extensions; + const { gl } = this; if (this.webGLVersion === 1) { - extensions.drawBuffers = gl.getExtension('WEBGL_draw_buffers'); - extensions.depthTexture = gl.getExtension('WEBKIT_WEBGL_depth_texture'); - extensions.floatTexture = gl.getExtension('OES_texture_float'); - extensions.loseContext = gl.getExtension('WEBGL_lose_context'); - - extensions.vertexArrayObject = gl.getExtension('OES_vertex_array_object') - || gl.getExtension('MOZ_OES_vertex_array_object') - || gl.getExtension('WEBKIT_OES_vertex_array_object'); + Object.assign(this.extensions, { + drawBuffers: gl.getExtension('WEBGL_draw_buffers'), + depthTexture: gl.getExtension('WEBKIT_WEBGL_depth_texture'), + floatTexture: gl.getExtension('OES_texture_float'), + loseContext: gl.getExtension('WEBGL_lose_context'), + vertexArrayObject: gl.getExtension('OES_vertex_array_object') + || gl.getExtension('MOZ_OES_vertex_array_object') + || gl.getExtension('WEBKIT_OES_vertex_array_object'), + }); } // we don't use any specific WebGL 2 ones yet! @@ -163,11 +203,22 @@ } } + /** + * Handle the post-render runner event + * + * @private + */ postrender() { this.gl.flush(); } + /** + * Validate context + * + * @private + * @param {WebGLRenderingContext} gl - Render context + */ validateContext(gl) { const attributes = gl.getContextAttributes(); diff --git a/packages/core/src/filters/Filter.js b/packages/core/src/filters/Filter.js index 77c0e69..7e34a1a 100644 --- a/packages/core/src/filters/Filter.js +++ b/packages/core/src/filters/Filter.js @@ -237,6 +237,7 @@ * The default vertex shader source * * @static + * @type {string} * @constant */ static get defaultVertexSrc() @@ -248,6 +249,7 @@ * The default fragment shader source * * @static + * @type {string} * @constant */ static get defaultFragmentSrc() diff --git a/packages/core/src/filters/FilterSystem.js b/packages/core/src/filters/FilterSystem.js index f6e7819..d233ef6 100644 --- a/packages/core/src/filters/FilterSystem.js +++ b/packages/core/src/filters/FilterSystem.js @@ -9,24 +9,59 @@ import UniformGroup from '../shader/UniformGroup'; import { DRAW_MODES } from '@pixi/constants'; -// /** - * @ignore + * Internal class to manage filter state * @class + * @private */ class FilterState { - /** - * - */ constructor() { this.renderTexture = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @private + */ this.sourceFrame = new Rectangle(); + + /** + * Destination frame + * @member {PIXI.Rectangle} + * @private + */ this.destinationFrame = new Rectangle(); + + /** + * Collection of filters + * @member {PIXI.Filter[]} + * @private + */ this.filters = []; + + /** + * Target + * @member {PIXI.DisplayObject} + * @private + */ this.target = null; + + /** + * Compatibility with PixiJS v4 filters + * @member {boolean} + * @default false + * @private + */ this.legacy = false; + + /** + * Resolution of filters + * @member {number} + * @default 1 + * @private + */ this.resolution = 1; } } @@ -34,6 +69,7 @@ const screenKey = 'screen'; /** + * Manage the rendering of filters within PixiJS * @class * @memberof PIXI.systems * @extends PIXI.System @@ -49,22 +85,26 @@ /** * stores a bunch of PO2 textures used for filtering - * @type {Object} + * @member {Object} */ this.texturePool = {}; /** * a pool for storing filter states, save us creating new ones each tick - * @type {Array} + * @member {Array} */ this.statePool = []; /** * A very simple geometry used when drawing a filter effect to the screen - * @type {Quad} + * @member {PIXI.Quad} */ this.quad = new Quad(); + /** + * Quad UVs + * @member {PIXI.QuadUv} + */ this.quadUv = new QuadUv(); /** @@ -73,11 +113,22 @@ */ this.tempRect = new Rectangle(); + /** + * Active state + * @member {object} + */ this.activeState = {}; /** - * this uniform group is attached to filter uniforms when used - * @type {UniformGroup} + * This uniform group is attached to filter uniforms when used + * @member {PIXI.UniformGroup} + * @property {PIXI.Rectangle} outputFrame + * @property {Float32Array} inputSize + * @property {Float32Array} inputPixel + * @property {Float32Array} inputClamp + * @property {Number} resolution + * @property {Float32Array} filterArea + * @property {Fload32Array} filterClamp */ this.globalUniforms = new UniformGroup({ outputFrame: this.tempRect, @@ -92,7 +143,6 @@ }, true); this._pixelsWidth = renderer.view.width; - this._pixelsHeight = renderer.view.height; } diff --git a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js index 6d1787b..564b0e6 100644 --- a/packages/core/src/filters/spriteMask/SpriteMaskFilter.js +++ b/packages/core/src/filters/spriteMask/SpriteMaskFilter.js @@ -24,7 +24,16 @@ sprite.renderable = false; + /** + * Sprite mask + * @member {PIXI.Sprite} + */ this.maskSprite = sprite; + + /** + * Mask matrix + * @member {PIXI.Matrix} + */ this.maskMatrix = maskMatrix; } diff --git a/packages/core/src/framebuffer/FramebufferSystem.js b/packages/core/src/framebuffer/FramebufferSystem.js index d949a85..15d5fc1 100644 --- a/packages/core/src/framebuffer/FramebufferSystem.js +++ b/packages/core/src/framebuffer/FramebufferSystem.js @@ -2,6 +2,7 @@ import { Rectangle } from '@pixi/math'; /** + * Framebuffer system * @class * @extends PIXI.System * @memberof PIXI.systems @@ -19,13 +20,18 @@ this.CONTEXT_UID = this.renderer.CONTEXT_UID; this.current = null; this.viewport = new Rectangle(); - this.drawBufferExtension = this.renderer.context.extensions.drawBuffers; } + /** + * Bind a framebuffer + * + * @param {PIXI.Framebuffer} framebuffer + * @param {PIXI.Rectangle} frame + */ bind(framebuffer, frame) { - const gl = this.gl; + const { gl } = this; this.current = framebuffer; @@ -96,6 +102,14 @@ } } + /** + * Set the WebGLRenderingContext's viewport. + * + * @param {Number} x - X position of viewport + * @param {Number} y - Y position of viewport + * @param {Number} width - Width of viewport + * @param {Number} height - Height of viewport + */ setViewport(x, y, width, height) { const v = this.viewport; @@ -111,6 +125,12 @@ } } + /** + * Get the size of the current width and height. Returns object with `width` and `height` values. + * + * @member {object} + * @readonly + */ get size() { if (this.current) @@ -122,20 +142,32 @@ return { x: 0, y: 0, width: this.renderer.width, height: this.renderer.height }; } + /** + * Clear the color of the context + * + * @param {Number} r - Red value from 0 to 1 + * @param {Number} g - Green value from 0 to 1 + * @param {Number} b - Blue value from 0 to 1 + * @param {Number} a - Alpha value from 0 to 1 + */ clear(r, g, b, a) { - const gl = this.gl; + const { gl } = this; // TODO clear color can be set only one right? gl.clearColor(r, g, b, a); gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); } - // private functions... - + /** + * Initialize framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ initFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; // TODO - make this a class? const fbo = { @@ -151,9 +183,15 @@ return fbo; } + /** + * Resize the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ resizeFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; if (framebuffer.stencil || framebuffer.depth) { @@ -162,9 +200,15 @@ } } + /** + * Update the framebuffer + * + * @private + * @param {PIXI.Framebuffer} framebuffer + */ updateFramebuffer(framebuffer) { - const gl = this.gl; + const { gl } = this; const fbo = framebuffer.glFrameBuffers[this.CONTEXT_UID]; diff --git a/packages/core/src/geometry/Geometry.js b/packages/core/src/geometry/Geometry.js index c6388c8..1913d44 100644 --- a/packages/core/src/geometry/Geometry.js +++ b/packages/core/src/geometry/Geometry.js @@ -43,13 +43,13 @@ * @param {array} [buffers] an array of buffers. optional. * @param {object} [attributes] of the geometry, optional structure of the attributes layout */ - constructor(buffers, attributes) + constructor(buffers = [], attributes = {}) { - this.buffers = buffers || []; + this.buffers = buffers; this.indexBuffer = null; - this.attributes = attributes || {}; + this.attributes = attributes; /** * A map of renderer IDs to webgl VAOs diff --git a/packages/core/src/geometry/GeometrySystem.js b/packages/core/src/geometry/GeometrySystem.js index 29b2f87..881674d 100644 --- a/packages/core/src/geometry/GeometrySystem.js +++ b/packages/core/src/geometry/GeometrySystem.js @@ -22,7 +22,18 @@ this._activeGeometry = null; this._activeVao = null; + /** + * `true` if we has `*_vertex_array_object` extension + * @member {boolean} + * @readonly + */ this.hasVao = true; + + /** + * `true` if has `ANGLE_instanced_arrays` extension + * @member {boolean} + * @readonly + */ this.hasInstance = true; } @@ -105,12 +116,13 @@ * Binds geometry so that is can be drawn. Creating a Vao if required * @private * @param {PIXI.Geometry} geometry instance of geometry to bind + * @param {PIXI.Shader} shader instance of shader to bind */ bind(geometry, shader) { shader = shader || this.renderer.shader.shader; - const gl = this.gl; + const { gl } = this; // not sure the best way to address this.. // currently different shaders require different VAOs for the same geometry @@ -147,15 +159,22 @@ this.updateBuffers(); } + /** + * Reset and unbind any active VAO and geometry + */ reset() { this.unbind(); } + /** + * Update buffers + * @private + */ updateBuffers() { const geometry = this._activeGeometry; - const gl = this.gl; + const { gl } = this; for (let i = 0; i < geometry.buffers.length; i++) { @@ -187,6 +206,12 @@ } } + /** + * Check compability between a geometry and a program + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Program instance + */ checkCompatibility(geometry, program) { // geometry must have at least all the attributes that the shader requires. @@ -205,7 +230,8 @@ /** * Creates a Vao with the same structure as the geometry and stores it on the geometry. * @private - * @param {PIXI.Geometry} geometry instance of geometry to to generate Vao for + * @param {PIXI.Geometry} geometry - Instance of geometry to to generate Vao for + * @param {PIXI.Program} program - Instance of program */ initGeometryVao(geometry, program) { @@ -288,6 +314,13 @@ return vao; } + /** + * Activate vertex array object + * + * @private + * @param {PIXI.Geometry} geometry - Geometry instance + * @param {PIXI.Program} program - Shader program instance + */ activateVao(geometry, program) { const gl = this.gl; @@ -348,9 +381,17 @@ } } + /** + * Draw the geometry + * + * @param {Number} type - the type primitive to render + * @param {Number} [size] - the number of elements to be rendered + * @param {Number} [start] - Starting index + * @param {Number} [instanceCount] - the number of instances of the set of elements to execute + */ draw(type, size, start, instanceCount) { - const gl = this.gl; + const { gl } = this; const geometry = this._activeGeometry; // TODO.. this should not change so maybe cache the function? @@ -368,8 +409,7 @@ gl.drawElements(type, size || geometry.indexBuffer.data.length, gl.UNSIGNED_SHORT, (start || 0) * 2); } } - else - if (geometry.instanced) + else if (geometry.instanced) { // TODO need a better way to calculate size.. gl.drawArraysInstanced(type, start, size || geometry.getSize(), instanceCount || 1); @@ -382,6 +422,10 @@ return this; } + /** + * Unbind/reset everything + * @private + */ unbind() { this.gl.bindVertexArray(null); diff --git a/packages/core/src/mask/MaskSystem.js b/packages/core/src/mask/MaskSystem.js index 0dc3e50..04607c1 100644 --- a/packages/core/src/mask/MaskSystem.js +++ b/packages/core/src/mask/MaskSystem.js @@ -1,5 +1,5 @@ import System from '../System'; -import AlphaMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; +import SpriteMaskFilter from '../filters/spriteMask/SpriteMaskFilter'; /** * @class @@ -16,13 +16,47 @@ super(renderer); // TODO - we don't need both! + /** + * `true` if current pushed masked is scissor + * @member {boolean} + * @readonly + */ this.scissor = false; + + /** + * Mask data + * @member {PIXI.Graphics} + * @readonly + */ this.scissorData = null; + + /** + * Target to mask + * @member {PIXI.DisplayObject} + * @readonly + */ this.scissorRenderTarget = null; + /** + * Enable scissor + * @member {boolean} + * @readonly + */ this.enableScissor = false; + /** + * Pool of used sprite mask filters + * @member {PIXI.SpriteMaskFilter[]} + * @readonly + */ this.alphaMaskPool = []; + + /** + * Current index of alpha mask pool + * @member {number} + * @default 0 + * @readonly + */ this.alphaMaskIndex = 0; } @@ -104,7 +138,7 @@ if (!alphaMaskFilter) { - alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new AlphaMaskFilter(maskData)]; + alphaMaskFilter = this.alphaMaskPool[this.alphaMaskIndex] = [new SpriteMaskFilter(maskData)]; } alphaMaskFilter[0].resolution = this.renderer.resolution; @@ -182,7 +216,7 @@ } /** - * + * Pop scissor mask * */ popScissorMask() @@ -192,7 +226,7 @@ this.scissor = false; // must be scissor! - const gl = this.renderer.gl; + const { gl } = this.renderer; gl.disable(gl.SCISSOR_TEST); } diff --git a/packages/core/src/mask/StencilSystem.js b/packages/core/src/mask/StencilSystem.js index 122c5d1..bf9ddae 100644 --- a/packages/core/src/mask/StencilSystem.js +++ b/packages/core/src/mask/StencilSystem.js @@ -13,6 +13,11 @@ constructor(renderer) { super(renderer); + + /** + * The mask stack + * @member {PIXI.Graphics[]} + */ this.stencilMaskStack = []; } @@ -102,6 +107,7 @@ /** * Setup renderer to use the current stencil data. + * @private */ _useCurrent() { @@ -114,7 +120,7 @@ /** * Fill 1s equal to the number of acitve stencil masks. - * + * @private * @return {number} The bitwise mask. */ _getBitwiseMask() diff --git a/packages/core/src/projection/ProjectionSystem.js b/packages/core/src/projection/ProjectionSystem.js index 6e63b73..b953079 100644 --- a/packages/core/src/projection/ProjectionSystem.js +++ b/packages/core/src/projection/ProjectionSystem.js @@ -16,9 +16,43 @@ { super(renderer); + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.destinationFrame = null; + + /** + * Source frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.sourceFrame = null; + + /** + * Default destination frame + * @member {PIXI.Rectangle} + * @readonly + */ + this.defaultFrame = null; + + /** + * Project matrix + * @member {PIXI.Matrix} + * @readonly + */ this.projectionMatrix = new Matrix(); } + /** + * Updates the projection matrix based on a projection frame (which is a rectangle) + * + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root + */ update(destinationFrame, sourceFrame, resolution, root) { this.destinationFrame = destinationFrame || this.destinationFrame || this.defaultFrame; @@ -33,8 +67,10 @@ /** * Updates the projection matrix based on a projection frame (which is a rectangle) * - * @param {Rectangle} destinationFrame - The destination frame. - * @param {Rectangle} sourceFrame - The source frame. + * @param {PIXI.Rectangle} destinationFrame - The destination frame. + * @param {PIXI.Rectangle} sourceFrame - The source frame. + * @param {Number} resolution - Resolution + * @param {boolean} root - If is root */ calculateProjection(destinationFrame, sourceFrame, resolution, root) { diff --git a/packages/core/src/renderTexture/RenderTextureSystem.js b/packages/core/src/renderTexture/RenderTextureSystem.js index 3b7bcf0..46349b5 100644 --- a/packages/core/src/renderTexture/RenderTextureSystem.js +++ b/packages/core/src/renderTexture/RenderTextureSystem.js @@ -18,18 +18,50 @@ { super(renderer); + /** + * The clear background color as rgba + * @member {number[]} + */ this.clearColor = renderer._backgroundColorRgba; - // TODO moe this property somewhere else! + // TODO move this property somewhere else! + /** + * List of masks for the StencilSystem + * @member {Array} + * @readonly + */ this.defaultMaskStack = []; + + /** + * List of filters for the FilterSystem + * @member {Array} + * @readonly + */ this.defaultFilterStack = [{}]; // empty render texture? + /** + * Render texture + * @member {PIXI.RenderTexture} + * @readonly + */ this.renderTexture = null; + /** + * Destination frame + * @member {PIXI.Rectangle} + * @readonly + */ this.destinationFrame = new Rectangle(); } + /** + * Bind the current render texture + * @private + * @param {PIXI.RenderTexture} renderTexture + * @param {PIXI.Rectangle} sourceFrame + * @param {PIXI.Rectangle} destinationFrame + */ bind(renderTexture, sourceFrame, destinationFrame) { // TODO - do we want this?? @@ -100,7 +132,7 @@ /** * Erases the render texture and fills the drawing area with a colour * - * @param {number} [clearColor] - The colour + * @param {number[]} [clearColor] - The color as rgba, default to use the renderer backgroundColor * @return {PIXI.Renderer} Returns itself. */ clear(clearColor) diff --git a/packages/core/src/state/StateSystem.js b/packages/core/src/state/StateSystem.js index df4044a..a29d215 100755 --- a/packages/core/src/state/StateSystem.js +++ b/packages/core/src/state/StateSystem.js @@ -1,6 +1,6 @@ import mapWebGLBlendModesToPixi from './utils/mapWebGLBlendModesToPixi'; import System from '../System'; -import WebGLState from './State'; +import State from './State'; const BLEND = 0; const OFFSET = 1; @@ -12,31 +12,75 @@ * A WebGL state machines * * @class - * @extends PIXI.systems.System + * @extends PIXI.System * @memberof PIXI.systems */ export default class StateSystem extends System { /** - * @param {WebGLRenderingContext} gl - The current WebGL rendering context + * @param {PIXI.Renderer} renderer - Reference to renderer */ constructor(renderer) { super(renderer); + /** + * GL context + * @member {WebGLRenderingContext} + * @readonly + */ this.gl = null; + /** + * Return from MAX_VERTEX_ATTRIBS + * @member {number} + * @readonly + */ this.maxAttribs = null; - // check we have vao.. + /** + * Check we have vao + * @member {OES_vertex_array_object} + * @readonly + */ this.nativeVaoExtension = null; + /** + * Attribute state + * @member {object} + * @readonly + * @property {Array} tempAttribState + * @property {Array} attribState + */ this.attribState = null; + /** + * State ID + * @member {number} + * @readonly + */ this.stateId = 0; + + /** + * Polygon offset + * @member {number} + * @readonly + */ this.polygonOffset = 0; + + /** + * Blend mode + * @member {number} + * @default 17 + * @readonly + */ this.blendMode = 17; + /** + * Collection of calls + * @member {function[]} + * @readonly + */ this.map = []; // map functions for when we set state.. @@ -46,20 +90,25 @@ this.map[DEPTH_TEST] = this.setDepthTest; this.map[WINDING] = this.setFrontFace; + /** + * Collection of check calls + * @member {function[]} + * @readonly + */ this.checks = []; - this.defaultState = new WebGLState(); + /** + * Default WebGL State + * @member {PIXI.State} + * @readonly + */ + this.defaultState = new State(); this.defaultState.blend = true; this.defaultState.depth = true; } contextChange(gl) { - /** - * The current WebGL rendering context - * - * @member {WebGLRenderingContext} - */ this.gl = gl; this.maxAttribs = gl.getParameter(gl.MAX_VERTEX_ATTRIBS); diff --git a/packages/core/src/textures/TextureGCSystem.js b/packages/core/src/textures/TextureGCSystem.js index 6d07606..90477ce 100644 --- a/packages/core/src/textures/TextureGCSystem.js +++ b/packages/core/src/textures/TextureGCSystem.js @@ -19,10 +19,39 @@ { super(renderer); + /** + * Count + * @member {number} + * @readonly + */ this.count = 0; + + /** + * Check count + * @member {number} + * @readonly + */ this.checkCount = 0; + + /** + * Maximum idle time, in seconds + * @member {number} + * @see PIXI.settings.GC_MAX_IDLE + */ this.maxIdle = settings.GC_MAX_IDLE; + + /** + * Maximum number of itesm to check + * @member {number} + * @see PIXI.settings.GC_MAX_CHECK_COUNT + */ this.checkCountMax = settings.GC_MAX_CHECK_COUNT; + + /** + * Current garabage collection mode + * @member {PIXI.GC_MODES} + * @see PIXI.settings.GC_MODE + */ this.mode = settings.GC_MODE; } diff --git a/packages/core/src/textures/TextureSystem.js b/packages/core/src/textures/TextureSystem.js index e4fdd9c..b9b3ecc 100644 --- a/packages/core/src/textures/TextureSystem.js +++ b/packages/core/src/textures/TextureSystem.js @@ -17,6 +17,11 @@ super(renderer); // TODO set to max textures... + /** + * Bound textures + * @member {PIXI.BaseTexture[]} + * @readonly + */ this.boundTextures = [ null, null, @@ -37,8 +42,18 @@ null, ]; + /** + * Current location + * @member {number} + * @readonly + */ this.currentLocation = -1; + /** + * List of managed textures + * @member {PIXI.BaseTextures[]} + * @readonly + */ this.managedTextures = []; } @@ -82,11 +97,15 @@ } } - bind(texture, location) + /** + * Bind a texture to a specific location + * + * @param {PIXI.Texture|PIXI.BaseTexture} texture - Texture to bind + * @param {number} [location=0] - Location to bind at + */ + bind(texture, location = 0) { - const gl = this.gl; - - location = location || 0; + const { gl } = this; if (this.currentLocation !== location) { @@ -121,9 +140,13 @@ } } + /** + * Unbind a texture + * @param {PIXI.Texture|PIXI.BaseTexture} texture - Texture to bind + */ unbind(texture) { - const gl = this.gl; + const { gl } = this; for (let i = 0; i < this.boundTextures.length; i++) { @@ -141,6 +164,12 @@ } } + /** + * Initialize a texture + * + * @private + * @param {PIXI.BaseTexture} texture - Texture to initialize + */ initTexture(texture) { const glTexture = new GLTexture(this.gl.createTexture()); @@ -156,6 +185,12 @@ return glTexture; } + /** + * Update a texture + * + * @private + * @param {PIXI.BaseTexture} texture - Texture to initialize + */ updateTexture(texture) { const glTexture = texture._glTextures[this.CONTEXT_UID]; @@ -201,12 +236,13 @@ /** * Deletes the texture from WebGL * + * @private * @param {PIXI.BaseTexture|PIXI.Texture} texture - the texture to destroy * @param {boolean} [skipRemove=false] - Whether to skip removing the texture from the TextureManager. */ destroyTexture(texture, skipRemove) { - const gl = this.gl; + const { gl } = this; texture = texture.baseTexture || texture; @@ -231,6 +267,12 @@ } } + /** + * Update texture style such as mipmap flag + * + * @private + * @param {PIXI.BaseTexture} texture - Texture to update + */ updateTextureStyle(texture) { const glTexture = texture._glTextures[this.CONTEXT_UID]; @@ -253,6 +295,13 @@ glTexture.dirtyStyleId = texture.dirtyStyleId; } + /** + * Set style for texture + * + * @private + * @param {PIXI.BaseTexture} texture - Texture to update + * @param {glTexture} glTexture + */ setStyle(texture, glTexture) { const gl = this.gl;