phaser/src/gameobjects/blitter/Blitter.js

294 lines
9.9 KiB
JavaScript
Raw Normal View History

2018-02-12 16:01:20 +00:00
/**
* @author Richard Davey <rich@photonstorm.com>
2020-01-15 12:07:09 +00:00
* @copyright 2020 Photon Storm Ltd.
2019-05-10 15:15:04 +00:00
* @license {@link https://opensource.org/licenses/MIT|MIT License}
2018-02-12 16:01:20 +00:00
*/
var BlitterRender = require('./BlitterRender');
var Bob = require('./Bob');
var Class = require('../../utils/Class');
var Components = require('../components');
var Frame = require('../../textures/Frame');
var GameObject = require('../GameObject');
var List = require('../../structs/List');
2018-03-19 21:27:16 +00:00
/**
* @callback CreateCallback
2018-03-19 21:27:16 +00:00
*
2019-02-01 18:02:58 +00:00
* @param {Phaser.GameObjects.Bob} bob - The Bob that was created by the Blitter.
* @param {integer} index - The position of the Bob within the Blitter display list.
2018-03-19 21:27:16 +00:00
*/
2018-01-31 13:54:44 +00:00
/**
2018-02-07 15:27:21 +00:00
* @classdesc
2018-01-31 13:54:44 +00:00
* A Blitter Game Object.
*
2018-02-06 14:13:30 +00:00
* The Blitter Game Object is a special kind of container that creates, updates and manages Bob objects.
* Bobs are designed for rendering speed rather than flexibility. They consist of a texture, or frame from a texture,
* a position and an alpha value. You cannot scale or rotate them. They use a batched drawing method for speed
* during rendering.
*
* A Blitter Game Object has one texture bound to it. Bobs created by the Blitter can use any Frame from this
* Texture to render with, but they cannot use any other Texture. It is this single texture-bind that allows
* them their speed.
*
* If you have a need to blast a large volume of frames around the screen then Blitter objects are well worth
* investigating. They are especially useful for using as a base for your own special effects systems.
2018-01-31 13:54:44 +00:00
*
* @class Blitter
* @extends Phaser.GameObjects.GameObject
2018-10-10 09:49:13 +00:00
* @memberof Phaser.GameObjects
2018-01-31 13:54:44 +00:00
* @constructor
* @since 3.0.0
*
2018-02-01 00:04:45 +00:00
* @extends Phaser.GameObjects.Components.Alpha
2018-02-01 01:20:11 +00:00
* @extends Phaser.GameObjects.Components.BlendMode
* @extends Phaser.GameObjects.Components.Depth
* @extends Phaser.GameObjects.Components.Mask
2018-02-01 01:20:11 +00:00
* @extends Phaser.GameObjects.Components.Pipeline
* @extends Phaser.GameObjects.Components.ScrollFactor
* @extends Phaser.GameObjects.Components.Size
* @extends Phaser.GameObjects.Components.Texture
* @extends Phaser.GameObjects.Components.Transform
* @extends Phaser.GameObjects.Components.Visible
2018-03-19 21:27:16 +00:00
*
2018-01-31 13:54:44 +00:00
* @param {Phaser.Scene} scene - The Scene to which this Game Object belongs. It can only belong to one Scene at any given time.
2018-02-05 23:59:51 +00:00
* @param {number} [x=0] - The x coordinate of this Game Object in world space.
2018-01-31 13:54:44 +00:00
* @param {number} [y=0] - The y coordinate of this Game Object in world space.
* @param {string} [texture='__DEFAULT'] - The key of the texture this Game Object will use for rendering. The Texture must already exist in the Texture Manager.
2018-03-20 14:56:31 +00:00
* @param {(string|integer)} [frame=0] - The Frame of the Texture that this Game Object will use. Only set if the Texture has multiple frames, such as a Texture Atlas or Sprite Sheet.
2018-01-31 13:54:44 +00:00
*/
var Blitter = new Class({
2017-04-05 01:10:48 +00:00
Extends: GameObject,
Mixins: [
Components.Alpha,
Components.BlendMode,
Components.Depth,
Components.Mask,
2018-01-29 21:46:48 +00:00
Components.Pipeline,
2018-02-01 01:20:11 +00:00
Components.ScrollFactor,
2017-03-02 02:06:22 +00:00
Components.Size,
Components.Texture,
Components.Transform,
Components.Visible,
BlitterRender
],
2017-01-24 12:55:45 +00:00
initialize:
function Blitter (scene, x, y, texture, frame)
{
GameObject.call(this, scene, 'Blitter');
this.setTexture(texture, frame);
2017-03-02 02:06:22 +00:00
this.setPosition(x, y);
this.initPipeline();
2018-01-26 15:37:34 +00:00
/**
* The children of this Blitter.
* This List contains all of the Bob objects created by the Blitter.
2018-01-26 15:37:34 +00:00
*
2018-02-01 00:04:45 +00:00
* @name Phaser.GameObjects.Blitter#children
2019-02-01 18:02:58 +00:00
* @type {Phaser.Structs.List.<Phaser.GameObjects.Bob>}
2018-01-26 15:37:34 +00:00
* @since 3.0.0
*/
this.children = new List();
2018-01-26 15:37:34 +00:00
/**
* A transient array that holds all of the Bobs that will be rendered this frame.
* The array is re-populated whenever the dirty flag is set.
2018-01-26 15:37:34 +00:00
*
2018-02-01 00:04:45 +00:00
* @name Phaser.GameObjects.Blitter#renderList
2019-02-01 18:02:58 +00:00
* @type {Phaser.GameObjects.Bob[]}
2018-01-26 15:37:34 +00:00
* @default []
* @private
2018-01-26 15:37:34 +00:00
* @since 3.0.0
*/
this.renderList = [];
/**
* Is the Blitter considered dirty?
* A 'dirty' Blitter has had its child count changed since the last frame.
*
* @name Phaser.GameObjects.Blitter#dirty
* @type {boolean}
* @since 3.0.0
*/
this.dirty = false;
},
2018-01-26 15:37:34 +00:00
/**
* Creates a new Bob in this Blitter.
*
* The Bob is created at the given coordinates, relative to the Blitter and uses the given frame.
* A Bob can use any frame belonging to the texture bound to the Blitter.
2018-01-26 15:37:34 +00:00
*
* @method Phaser.GameObjects.Blitter#create
* @since 3.0.0
*
* @param {number} x - The x position of the Bob. Bob coordinate are relative to the position of the Blitter object.
* @param {number} y - The y position of the Bob. Bob coordinate are relative to the position of the Blitter object.
2018-03-20 14:56:31 +00:00
* @param {(string|integer|Phaser.Textures.Frame)} [frame] - The Frame the Bob will use. It _must_ be part of the Texture the parent Blitter object is using.
2018-01-26 15:37:34 +00:00
* @param {boolean} [visible=true] - Should the created Bob render or not?
* @param {integer} [index] - The position in the Blitters Display List to add the new Bob at. Defaults to the top of the list.
*
2019-02-01 18:02:58 +00:00
* @return {Phaser.GameObjects.Bob} The newly created Bob object.
2018-01-26 15:37:34 +00:00
*/
create: function (x, y, frame, visible, index)
{
if (visible === undefined) { visible = true; }
if (index === undefined) { index = this.children.length; }
if (frame === undefined)
{
frame = this.frame;
}
else if (!(frame instanceof Frame))
{
frame = this.texture.get(frame);
}
2017-10-02 13:50:02 +00:00
var bob = new Bob(this, x, y, frame, visible);
this.children.addAt(bob, index, false);
this.dirty = true;
return bob;
},
2017-01-24 12:55:45 +00:00
2018-01-26 15:37:34 +00:00
/**
* Creates multiple Bob objects within this Blitter and then passes each of them to the specified callback.
2018-01-26 15:37:34 +00:00
*
* @method Phaser.GameObjects.Blitter#createFromCallback
* @since 3.0.0
*
* @param {CreateCallback} callback - The callback to invoke after creating a bob. It will be sent two arguments: The Bob and the index of the Bob.
2018-02-01 05:48:56 +00:00
* @param {integer} quantity - The quantity of Bob objects to create.
2018-03-23 15:54:12 +00:00
* @param {(string|integer|Phaser.Textures.Frame|string[]|integer[]|Phaser.Textures.Frame[])} [frame] - The Frame the Bobs will use. It must be part of the Blitter Texture.
* @param {boolean} [visible=true] - Should the created Bob render or not?
2018-01-26 15:37:34 +00:00
*
2019-02-01 18:02:58 +00:00
* @return {Phaser.GameObjects.Bob[]} An array of Bob objects that were created.
2018-01-26 15:37:34 +00:00
*/
createFromCallback: function (callback, quantity, frame, visible)
2017-01-24 12:55:45 +00:00
{
var bobs = this.createMultiple(quantity, frame, visible);
for (var i = 0; i < bobs.length; i++)
{
var bob = bobs[i];
callback.call(this, bob, i);
}
return bobs;
},
2018-01-26 15:37:34 +00:00
/**
* Creates multiple Bobs in one call.
*
* The amount created is controlled by a combination of the `quantity` argument and the number of frames provided.
*
* If the quantity is set to 10 and you provide 2 frames, then 20 Bobs will be created. 10 with the first
* frame and 10 with the second.
2018-01-26 15:37:34 +00:00
*
* @method Phaser.GameObjects.Blitter#createMultiple
* @since 3.0.0
*
2018-02-01 05:48:56 +00:00
* @param {integer} quantity - The quantity of Bob objects to create.
2018-03-23 15:54:12 +00:00
* @param {(string|integer|Phaser.Textures.Frame|string[]|integer[]|Phaser.Textures.Frame[])} [frame] - The Frame the Bobs will use. It must be part of the Blitter Texture.
* @param {boolean} [visible=true] - Should the created Bob render or not?
2018-01-26 15:37:34 +00:00
*
2019-02-01 18:02:58 +00:00
* @return {Phaser.GameObjects.Bob[]} An array of Bob objects that were created.
2018-01-26 15:37:34 +00:00
*/
createMultiple: function (quantity, frame, visible)
2017-01-24 12:55:45 +00:00
{
2018-01-20 16:35:47 +00:00
if (frame === undefined) { frame = this.frame.name; }
if (visible === undefined) { visible = true; }
if (!Array.isArray(frame))
{
frame = [ frame ];
}
var bobs = [];
var _this = this;
2017-01-24 12:55:45 +00:00
frame.forEach(function (singleFrame)
{
for (var i = 0; i < quantity; i++)
{
bobs.push(_this.create(0, 0, singleFrame, visible));
}
});
return bobs;
},
2018-01-26 15:37:34 +00:00
/**
* Checks if the given child can render or not, by checking its `visible` and `alpha` values.
2018-01-26 15:37:34 +00:00
*
* @method Phaser.GameObjects.Blitter#childCanRender
* @since 3.0.0
*
2019-02-01 18:02:58 +00:00
* @param {Phaser.GameObjects.Bob} child - The Bob to check for rendering.
2018-01-26 15:37:34 +00:00
*
* @return {boolean} Returns `true` if the given child can render, otherwise `false`.
2018-01-26 15:37:34 +00:00
*/
childCanRender: function (child)
2017-01-24 12:55:45 +00:00
{
return (child.visible && child.alpha > 0);
},
2018-01-26 15:37:34 +00:00
/**
* Returns an array of Bobs to be rendered.
* If the Blitter is dirty then a new list is generated and stored in `renderList`.
2018-01-26 15:37:34 +00:00
*
* @method Phaser.GameObjects.Blitter#getRenderList
* @since 3.0.0
*
2019-02-01 18:02:58 +00:00
* @return {Phaser.GameObjects.Bob[]} An array of Bob objects that will be rendered this frame.
2018-01-26 15:37:34 +00:00
*/
getRenderList: function ()
{
if (this.dirty)
{
this.renderList = this.children.list.filter(this.childCanRender, this);
this.dirty = false;
}
return this.renderList;
},
2018-01-26 15:37:34 +00:00
/**
* Removes all Bobs from the children List and clears the dirty flag.
2018-01-26 15:37:34 +00:00
*
* @method Phaser.GameObjects.Blitter#clear
* @since 3.0.0
*/
clear: function ()
{
this.children.removeAll();
this.dirty = true;
},
/**
* Internal destroy handler, called as part of the destroy process.
*
* @method Phaser.GameObjects.Blitter#preDestroy
* @protected
* @since 3.9.0
*/
preDestroy: function ()
{
this.children.destroy();
this.renderList = [];
}
});
module.exports = Blitter;