phaser/src/structs/ProcessQueue.js

227 lines
6 KiB
JavaScript
Raw Normal View History

2018-02-12 16:01:20 +00:00
/**
* @author Richard Davey <rich@photonstorm.com>
* @copyright 2018 Photon Storm Ltd.
* @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
*/
var Class = require('../utils/Class');
2018-02-09 04:35:23 +00:00
/**
* @classdesc
2018-10-19 14:53:04 +00:00
* A Process Queue maintains three internal lists.
*
* The `pending` list is a selection of items which are due to be made 'active' in the next update.
* The `active` list is a selection of items which are considered active and should be updated.
* The `destroy` list is a selection of items that were active and are awaiting being destroyed in the next update.
*
* When new items are added to a Process Queue they are put in a pending data, rather than being added
* immediately the active list. Equally, items that are removed are put into the destroy list, rather than
* being destroyed immediately. This allows the Process Queue to carefully process each item at a specific, fixed
* time, rather than at the time of the request from the API.
2018-02-09 04:35:23 +00:00
*
* @class ProcessQueue
2018-10-10 09:49:13 +00:00
* @memberof Phaser.Structs
2018-02-09 04:35:23 +00:00
* @constructor
* @since 3.0.0
*
* @generic T
2018-02-09 04:35:23 +00:00
*/
var ProcessQueue = new Class({
initialize:
function ProcessQueue ()
{
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* The `pending` list is a selection of items which are due to be made 'active' in the next update.
2018-02-09 04:35:23 +00:00
*
2018-03-29 10:56:47 +00:00
* @genericUse {T[]} - [$type]
*
2018-02-09 04:35:23 +00:00
* @name Phaser.Structs.ProcessQueue#_pending
2018-03-23 15:54:12 +00:00
* @type {Array.<*>}
2018-02-09 04:35:23 +00:00
* @private
* @default []
* @since 3.0.0
*/
this._pending = [];
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* The `active` list is a selection of items which are considered active and should be updated.
2018-02-09 04:35:23 +00:00
*
2018-03-29 10:56:47 +00:00
* @genericUse {T[]} - [$type]
*
2018-02-09 04:35:23 +00:00
* @name Phaser.Structs.ProcessQueue#_active
2018-03-23 15:54:12 +00:00
* @type {Array.<*>}
2018-02-09 04:35:23 +00:00
* @private
* @default []
* @since 3.0.0
*/
this._active = [];
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* The `destroy` list is a selection of items that were active and are awaiting being destroyed in the next update.
2018-02-09 04:35:23 +00:00
*
2018-03-29 10:56:47 +00:00
* @genericUse {T[]} - [$type]
*
2018-02-09 04:35:23 +00:00
* @name Phaser.Structs.ProcessQueue#_destroy
2018-03-23 15:54:12 +00:00
* @type {Array.<*>}
2018-02-09 04:35:23 +00:00
* @private
* @default []
* @since 3.0.0
*/
this._destroy = [];
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* The total number of items awaiting processing.
2018-02-09 04:35:23 +00:00
*
* @name Phaser.Structs.ProcessQueue#_toProcess
* @type {integer}
* @private
* @default 0
* @since 3.0.0
*/
this._toProcess = 0;
},
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* Adds a new item to the Process Queue.
* The item is added to the pending list and made active in the next update.
2018-02-09 04:35:23 +00:00
*
* @method Phaser.Structs.ProcessQueue#add
* @since 3.0.0
*
2018-03-29 10:56:47 +00:00
* @genericUse {T} - [item]
2018-03-30 12:43:58 +00:00
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
*
2018-10-19 14:53:04 +00:00
* @param {*} item - The item to add to the queue.
2018-02-09 04:35:23 +00:00
*
* @return {Phaser.Structs.ProcessQueue} This Process Queue object.
*/
add: function (item)
{
this._pending.push(item);
this._toProcess++;
return this;
},
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* Removes an item from the Process Queue.
* The item is added to the pending destroy and fully removed in the next update.
2018-02-09 04:35:23 +00:00
*
* @method Phaser.Structs.ProcessQueue#remove
* @since 3.0.0
*
2018-03-29 10:56:47 +00:00
* @genericUse {T} - [item]
2018-03-30 12:43:58 +00:00
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
*
2018-10-19 14:53:04 +00:00
* @param {*} item - The item to be removed from the queue.
2018-02-09 04:35:23 +00:00
*
* @return {Phaser.Structs.ProcessQueue} This Process Queue object.
*/
remove: function (item)
{
this._destroy.push(item);
this._toProcess++;
return this;
},
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* Update this queue. First it will process any items awaiting destruction, and remove them.
*
* Then it will check to see if there are any items pending insertion, and move them to an
* active state. Finally, it will return a list of active items for further processing.
2018-02-09 04:35:23 +00:00
*
* @method Phaser.Structs.ProcessQueue#update
* @since 3.0.0
*
2018-03-29 10:56:47 +00:00
* @genericUse {T[]} - [$return]
*
2018-10-19 14:53:04 +00:00
* @return {Array.<*>} A list of active items.
2018-02-09 04:35:23 +00:00
*/
update: function ()
{
if (this._toProcess === 0)
{
// Quick bail
return this._active;
}
var list = this._destroy;
var active = this._active;
var i;
var item;
// Clear the 'destroy' list
for (i = 0; i < list.length; i++)
{
item = list[i];
// Remove from the 'active' array
var idx = active.indexOf(item);
if (idx !== -1)
{
active.splice(idx, 1);
}
}
list.length = 0;
// Process the pending addition list
// This stops callbacks and out of sync events from populating the active array mid-way during an update
list = this._pending;
for (i = 0; i < list.length; i++)
{
item = list[i];
this._active.push(item);
}
list.length = 0;
this._toProcess = 0;
// The owner of this queue can now safely do whatever it needs to with the active list
return this._active;
},
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* Returns the current list of active items.
2018-02-09 04:35:23 +00:00
*
* @method Phaser.Structs.ProcessQueue#getActive
* @since 3.0.0
*
2018-03-29 10:56:47 +00:00
* @genericUse {T[]} - [$return]
*
2018-10-19 14:53:04 +00:00
* @return {Array.<*>} A list of active items.
2018-02-09 04:35:23 +00:00
*/
getActive: function ()
{
return this._active;
},
2018-02-09 04:35:23 +00:00
/**
2018-10-19 14:53:04 +00:00
* Immediately destroys this process queue, clearing all of its internal arrays and resetting the process totals.
2018-02-09 04:35:23 +00:00
*
* @method Phaser.Structs.ProcessQueue#destroy
* @since 3.0.0
*/
destroy: function ()
{
2018-10-19 14:53:04 +00:00
this._toProcess = 0;
this._pending = [];
this._active = [];
this._destroy = [];
}
});
module.exports = ProcessQueue;