fpv/source/libraries/noble/modules/Noble.Transition.lua
2024-06-01 16:52:11 +03:00

208 lines
9.4 KiB
Lua

--- An abstract class from which transition types are extended.
-- @module Noble.Transition
Noble.Transition = {}
class("Transition", nil, Noble).extends()
Noble.Transition.Type = {}
--- A transition type where no time at all passes between scenes.
-- @see Noble.Transition.Cut
Noble.Transition.Type.CUT = "Cut"
--- A transition type that has an "Enter" phase and an "Exit" phase. The new scene does not become active until the Enter phase is complete. A "holdTime" value determines how long to wait after the Enter phase completes before starting the Exit phase.
-- @see Noble.Transition.Dip
-- @see Noble.Transition.Imagetable
-- @see Noble.Transition.Spotlight
Noble.Transition.Type.COVER = "Cover"
--- A transition type that takes a screenshot of the exiting scene and activates the new scene before beginning the transition, allowing for both scenes to appear to be visible during the transition.
-- @see Noble.Transition.CrossDissolve
-- @see Noble.Transition.SlideOff
-- @see Noble.Transition.ImagetableMask
Noble.Transition.Type.MIX = "Mix"
--- A transition may have unique properties that can be set by the user when invoked. This table holds the default values for those properties.
-- @see setDefaultProperties
Noble.Transition.defaultProperties = {}
function Noble.Transition:init(__duration, __arguments)
self.duration = __duration or Noble.getConfig().defaultTransitionDuration
self.durationEnter = __arguments.durationEnter or self.duration/2
self.durationExit = __arguments.durationExit or self.duration/2
if (__arguments.durationEnter and not __arguments.durationExit) then
warn("Soft-BONK: You've specified 'durationEnter' but not 'durationExit' for this transition. Thus, 'durationExit' will be half the value of 'duration'. Did you intend to do that?")
elseif (__arguments.durationExit and not __arguments.durationEnter) then
warn("Soft-BONK: You've specified 'durationExit' but not 'durationEnter' for this transition. Thus, 'durationEnter' will be half the value of 'duration'. Did you intend to do that?")
end
self.sequence = nil
self._captureScreenshotsDuringTransition = self._captureScreenshotsDuringTransition or false
self.midpointReached = false
self.holdTimeElapsed = false
self.drawMode = self.drawMode or __arguments.drawMode or Graphics.kDrawModeCopy
self.holdTime = self.holdTime or __arguments.holdTime or self.defaultProperties.holdTime or 0
if (self._type == Noble.Transition.Type.MIX) then
self._sequenceStartValue = self._sequenceStartValue or 0
self._sequenceCompleteValue = self._sequenceCompleteValue or 1
self.ease = self.ease or __arguments.ease or self.defaultProperties.ease or Ease.linear
if ((__arguments.easeEnter or __arguments.easeExit) ~= nil) then
warn("BONK: You've specified an 'easeEnter' and/or 'easeExit' argument for a transition of type 'Noble.Transition.Type.MIX'. This will have no effect. Use 'ease' instead, or specify a transition of type 'Noble.Transition.Type.COVER'.")
end
self.oldSceneScreenshot = Utilities.screenshot()
elseif (self._type == Noble.Transition.Type.COVER) then
self._sequenceStartValue = self._sequenceStartValue or 0
self._sequenceMidpointValue = self._sequenceMidpointValue or 1
self._sequenceResumeValue = self._sequenceResumeValue or 1
self._sequenceCompleteValue = self._sequenceCompleteValue or 0
local ease = self.ease or __arguments.ease or self.defaultProperties.ease or Ease.linear
if (ease) then
self.easeEnter = self.easeEnter or self.defaultProperties.easeEnter or Ease.enter(ease) or ease
self.easeExit = self.easeExit or self.defaultProperties.easeExit or Ease.exit(ease) or ease
if (Ease.enter(ease) == nil or Ease.exit(ease) == nil) then
warn("Soft-BONK: You've specified an 'ease' value for a transition of type 'Noble.Transition.Type.COVER' that isn't in the form of 'Ease.inOutXxxx' or an 'Ease.outInXxxx'. As a result, this value will be used for both 'easeEnter' and 'easeExit'. Did you mean to do that?")
end
else
self.easeEnter = self.easeEnter or __arguments.easeEnter or self.defaultProperties.easeEnter or self.easeEnter or Ease.linear
self.easeExit = self.easeExit or __arguments.easeExit or self.defaultProperties.easeExit or self.easeExit or Ease.linear
end
end
self:setProperties(__arguments)
end
--- Use this to modify multiple default properties of a transition. Having default properties avoids having to set them every time a transition is called.
-- Properties added here are merged with the existing default properties table. Overwrites only happen when a new value is set.
-- @usage
-- Noble.Transition.setDefaultProperties(Noble.Transition.CrossDissolve, {
-- dither = Graphics.image.kDitherTypeDiagonalLine
-- ease = Ease.outQuint
-- })
-- Noble.Transition.setDefaultProperties(Noble.Transition.SpotlightMask, {
-- x = 325,
-- y = 95,
-- invert = true
-- })
-- @see defaultProperties
function Noble.Transition.setDefaultProperties(__transition, __properties)
table.merge(__transition.defaultProperties, __properties)
end
function Noble.Transition:execute()
local onStart = function()
Noble.transitionStartHandler()
self:onStart() -- If this transition has any custom code to run here, run it.
end
local onMidpoint = function()
Noble.transitionMidpointHandler()
self.midpointReached = true
self:onMidpoint() -- If this transition has any custom code to run here, run it.
end
local onHoldTimeElapsed = function()
self.holdTimeElapsed = true
self:onHoldTimeElapsed()
end
local onComplete = function()
self:onComplete() -- If this transition has any custom code to run here, run it.
Noble.transitionCompleteHandler()
end
local type = self._type
local holdTime = self.holdTime
if (type == Noble.Transition.Type.CUT) then
onStart()
onMidpoint()
onHoldTimeElapsed()
onComplete()
elseif (type == Noble.Transition.Type.COVER) then
onStart()
self.sequence = Sequence.new()
:from(self._sequenceStartValue)
:to(self._sequenceMidpointValue, self.durationEnter-(holdTime/2), self.easeEnter)
:callback(onMidpoint)
:sleep(holdTime)
:callback(onHoldTimeElapsed)
:to(self._sequenceResumeValue, 0)
:to(self._sequenceCompleteValue, self.durationExit-(holdTime/2), self.easeExit)
:callback(onComplete)
:start()
elseif (type == Noble.Transition.Type.MIX) then
onStart()
onMidpoint()
onHoldTimeElapsed()
self.sequence = Sequence.new()
:from(self._sequenceStartValue)
:to(self._sequenceCompleteValue, self.duration, self.ease)
:callback(onComplete)
:start()
end
end
--- *Do not call this directly.* Implement this in a custom transition in order to set properties from user arguments given in `Noble.transition()`. See existing transitions for implementation examples.
-- @see Noble.transition
function Noble.Transition:setProperties(__arguments) end
--- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition starts. Default transitions in Noble Engine do not use this.
function Noble.Transition:onStart() end
--- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition reaches its midpoint. Default transitions in Noble Engine do not use this.
function Noble.Transition:onMidpoint() end
--- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition's hold time has elapsed. Default transitions in Noble Engine do not use this.
function Noble.Transition:onHoldTimeElapsed() end
--- *Do not call this directly.* Implement this in a custom transition in order to run custom code when the transition completes. Default transitions in Noble Engine do not use this.
function Noble.Transition:onComplete() end
--- *Do not call this directly.* Implement this in a custom transition to draw the transition. This runs once per frame while the transition is running. See existing transitions for implementation examples.
function Noble.Transition:draw() end
-- Noble Engine built-in transitions.
import 'libraries/noble/modules/Noble.Transition/Cut.lua'
--
import 'libraries/noble/modules/Noble.Transition/CrossDissolve.lua'
import 'libraries/noble/modules/Noble.Transition/Dip.lua'
import 'libraries/noble/modules/Noble.Transition/DipToBlack.lua'
import 'libraries/noble/modules/Noble.Transition/DipToWhite.lua'
--
import 'libraries/noble/modules/Noble.Transition/Imagetable.lua'
import 'libraries/noble/modules/Noble.Transition/ImagetableMask.lua'
import 'libraries/noble/modules/Noble.Transition/Spotlight.lua'
import 'libraries/noble/modules/Noble.Transition/SpotlightMask.lua'
--
import 'libraries/noble/modules/Noble.Transition/SlideOff.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOffLeft.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOffRight.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOffUp.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOffDown.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOn.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOnLeft.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOnRight.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOnUp.lua'
import 'libraries/noble/modules/Noble.Transition/SlideOnDown.lua'
--
import 'libraries/noble/modules/Noble.Transition/MetroNexus.lua'
import 'libraries/noble/modules/Noble.Transition/WidgetSatchel.lua'