//------------------------------------------------------------------------------
// CONSTRUCTOR SCOPE
//------------------------------------------------------------------------------
/**
* Creates an application-owned manager for frozen scene-image transitions.
*
* @constructor
*
* @param {rune.system.Application} application Owning application.
*
* @class
* @classdesc
*
* select() and load() capture the old screen before requesting a scene change.
* Scenes performs normal lifecycle callbacks without running scene updates.
* Once pending lifecycle changes settle, the new screen is captured and the
* effect combines two frozen images. Cameras and scene timers remain paused.
* Captures exclude debug overlays. Only two extra internal-resolution canvases
* are allocated, once per operation. Calls while active return false. Resizing
* cancels the effect and reveals the current scene. Resources must be loaded
* before starting; asynchronous resource readiness is not inferred from init().
*/
rune.transition.Transitions = function(application) {
//--------------------------------------------------------------------------
// PRIVATE PROPERTIES
//--------------------------------------------------------------------------
/**
* Owning application; retained across scene batches.
*
* @type {rune.system.Application}
* @private
*/
this.m_application = application;
/**
* Current capture, switch, prepare or animation phase.
*
* @type {string}
* @private
*/
this.m_phase = "idle";
/**
* Effect owned while an operation is active.
*
* @type {rune.transition.Transition}
* @private
*/
this.m_effect = null;
/**
* Frozen previous screen image.
*
* @type {rune.display.Canvas}
* @private
*/
this.m_from = null;
/**
* Frozen next screen image.
*
* @type {rune.display.Canvas}
* @private
*/
this.m_to = null;
/**
* Copied batch request, or null for selection.
*
* @type {Array.<rune.scene.Scene>}
* @private
*/
this.m_batch = null;
/**
* Requested scene index.
*
* @type {number}
* @private
*/
this.m_index = 0;
/**
* Elapsed animation time in milliseconds.
*
* @type {number}
* @private
*/
this.m_elapsed = 0;
/**
* Duration captured when the request starts.
*
* @type {number}
* @private
*/
this.m_duration = 0;
};
//------------------------------------------------------------------------------
// PUBLIC GETTER AND SETTER METHODS
//------------------------------------------------------------------------------
/**
* Whether a capture, scene change or image transition is in progress.
*
* @member {boolean} active
* @memberof rune.transition.Transitions
* @instance
* @readonly
*/
Object.defineProperty(rune.transition.Transitions.prototype, "active", {
/**
* @this rune.transition.Transitions
* @ignore
*/
get : function() {
return this.m_phase !== "idle";
}
});
/**
* Normalized animation progress. Scene initialization does not advance it.
*
* @member {number} progress
* @memberof rune.transition.Transitions
* @instance
* @readonly
*/
Object.defineProperty(rune.transition.Transitions.prototype, "progress", {
/**
* @this rune.transition.Transitions
* @ignore
*/
get : function() {
return this.m_duration > 0 ? this.m_elapsed / this.m_duration : 0;
}
});
/**
* Whether the next capture needs the selected scene to render.
*
* @member {boolean} needsScene
* @memberof rune.transition.Transitions
* @instance
* @readonly
*/
Object.defineProperty(rune.transition.Transitions.prototype, "needsScene", {
/**
* @this rune.transition.Transitions
* @ignore
*/
get : function() {
return this.m_phase === "capture" || (this.m_phase === "prepare" &&
!this.m_application['scenes']['pending']);
}
});
//------------------------------------------------------------------------------
// PUBLIC PROTOTYPE METHODS (API)
//------------------------------------------------------------------------------
/**
* Starts an effect before selecting an index in the current scene batch.
* The effect is owned only when the request is accepted.
*
* @param {number} index Scene index, a zero-based integer.
* @param {rune.transition.Transition} effect Effect to play.
*
* @returns {boolean} Whether the request was accepted.
* @throws {RangeError} If index is outside the current batch.
* @throws {Error} If the manager is disposed or scene changes are pending.
*/
rune.transition.Transitions.prototype.select = function(index, effect) {
if (this['active']) {
return false;
}
this.m_validateRequest(effect);
if (typeof index !== "number" || index !== Math.floor(index) ||
index < 0 || index >= this.m_application['scenes']['batchSize']) {
throw new RangeError("Invalid transition scene index.");
}
this.m_index = index;
this.m_begin(effect);
return true;
};
/**
* Starts an effect before loading a copied scene batch. The scene manager
* validates its contents when the old image has been captured, before replacing
* current scenes. A rejected or cancelled request does not own the batch.
*
* @param {Array.<rune.scene.Scene>} batch New scene instances.
* @param {rune.transition.Transition} effect Effect to play.
*
* @returns {boolean} Whether the request was accepted.
* @throws {Error} If batch is empty, the manager is disposed or changes are pending.
*/
rune.transition.Transitions.prototype.load = function(batch, effect) {
if (this['active']) {
return false;
}
this.m_validateRequest(effect);
if (!Array.isArray(batch) || batch.length === 0) {
throw new Error("Invalid transition scene batch.");
}
this.m_batch = batch.slice();
this.m_begin(effect);
return true;
};
/**
* Ends an operation and releases images and effect resources. A scene change
* already submitted to Scenes is not rolled back. Before submission it is
* simply discarded, leaving the old scene selected.
*
* @returns {undefined}
*/
rune.transition.Transitions.prototype.cancel = function() {
var effect = this.m_effect;
var from = this.m_from;
var to = this.m_to;
this.m_phase = "idle";
this.m_effect = null;
this.m_from = null;
this.m_to = null;
this.m_batch = null;
this.m_elapsed = 0;
this.m_duration = 0;
if (from != null) {
from.dispose();
}
if (to != null) {
to.dispose();
}
if (effect != null) {
effect.dispose();
}
};
//------------------------------------------------------------------------------
// PUBLIC PROTOTYPE METHODS (ENGINE)
//------------------------------------------------------------------------------
/**
* Advances lifecycle preparation or animation without updating scene logic.
*
* @param {number} step Elapsed milliseconds.
*
* @returns {undefined}
* @ignore
*/
rune.transition.Transitions.prototype.update = function(step) {
try {
var scenes = this.m_application['scenes'];
if (this.m_phase === "switch") {
this.m_phase = "prepare";
if (this.m_batch != null) {
scenes.load(this.m_batch);
} else {
scenes.select(this.m_index);
}
this.m_batch = null;
scenes.update(0, false);
} else if (this.m_phase === "prepare") {
scenes.update(0, false);
} else if (this.m_phase === "animate") {
this.m_elapsed = Math.min(
this.m_duration,
this.m_elapsed + (isFinite(step) && step > 0 ? step : 0)
);
if (this.m_elapsed === this.m_duration) {
this.m_phase = "finish";
}
}
} catch (error) {
this.m_abort(error);
}
};
/**
* Captures clean screen content or composites the current effect frame.
* Returns false when Screen should render its normal content instead.
*
* @param {rune.display.Canvas} canvas Screen output canvas.
*
* @returns {boolean} Whether this operation supplied screen content.
* @ignore
*/
rune.transition.Transitions.prototype.render = function(canvas) {
if (!this['active']) {
return false;
}
try {
if (this.m_from != null && (this.m_from['width'] !== canvas['width'] ||
this.m_from['height'] !== canvas['height'])) {
this.cancel();
return false;
}
if (this.m_phase === "capture") {
this.m_application['screen'].renderContent();
this.m_from = this.m_capture(canvas);
this.m_phase = "switch";
} else if (this.m_phase === "prepare" &&
!this.m_application['scenes']['pending'] && this.m_application['scenes']['selected'] != null) {
this.m_application['screen'].renderContent();
this.m_to = this.m_capture(canvas);
this.m_effect.init(canvas['width'], canvas['height']);
this.m_phase = "animate";
}
canvas.clear();
if (this.m_to != null) {
var context = canvas['context'];
context.save();
try {
this.m_effect.render(canvas, this.m_from, this.m_to, this['progress']);
} finally {
context.restore();
}
if (this.m_phase === "finish") {
this.cancel();
}
} else {
canvas.drawImage(this.m_from['element'], 0, 0, canvas['width'], canvas['height']);
}
return true;
} catch (error) {
this.m_abort(error);
}
return false;
};
/**
* Releases the operation before the application disposes its scenes and screen.
*
* @returns {undefined}
* @ignore
*/
rune.transition.Transitions.prototype.dispose = function() {
try {
this.cancel();
} finally {
this.m_application = null;
}
};
//------------------------------------------------------------------------------
// PRIVATE PROTOTYPE METHODS
//------------------------------------------------------------------------------
/**
* Checks request prerequisites without changing scenes or claiming the effect.
*
* @param {rune.transition.Transition} effect Effect to validate.
*
* @returns {undefined}
* @private
*/
rune.transition.Transitions.prototype.m_validateRequest = function(effect) {
if (this.m_application == null) {
throw new Error("Transitions is disposed.");
}
if (!(effect instanceof rune.transition.Transition) ||
!isFinite(effect.duration) || effect.duration <= 0) {
throw new TypeError("A valid Transition effect is required.");
}
var scenes = this.m_application['scenes'];
if (scenes['pending'] || scenes['selected'] == null) {
throw new Error("A settled current scene is required for a transition.");
}
};
/**
* Claims an effect and waits for the old image's next rendering.
*
* @param {rune.transition.Transition} effect Accepted effect.
*
* @returns {undefined}
* @private
*/
rune.transition.Transitions.prototype.m_begin = function(effect) {
this.m_effect = effect;
this.m_duration = effect.duration;
this.m_elapsed = 0;
this.m_phase = "capture";
};
/**
* Copies the clean screen at its internal resolution without pixel readback.
*
* @param {rune.display.Canvas} canvas Source canvas.
*
* @returns {rune.display.Canvas} Owned snapshot.
* @private
*/
rune.transition.Transitions.prototype.m_capture = function(canvas) {
var image = new rune.display.Canvas(canvas['width'], canvas['height']);
image['smoothing'] = canvas['smoothing'];
image.drawImage(canvas['element'], 0, 0, canvas['width'], canvas['height']);
return image;
};
/**
* Releases an unsuccessful operation while preserving its original exception.
*
* @param {*} error Original lifecycle or rendering exception.
*
* @returns {undefined}
* @throws {*} The original error.
* @private
*/
rune.transition.Transitions.prototype.m_abort = function(error) {
try {
this.cancel();
} catch (cleanupError) {
// CLEANUP MUST NOT HIDE THE ORIGINAL ERROR.
}
throw error;
};