GuShH's Development Blog » animation

Animation lib

GuShH — Thu, 06 Aug 2009 21:43:43 +0000

Dependent on the time-lapse lib, the animation code provides you with several count methods to manipulate your animations in an easy and comprehensible way.

If you add a sprite atlas library (I’ll share later) you’ll be able to manipulate sprites with animation in quite a flexible way without too much hassle.

The idea is to encapsulate the animation functionality in such a way that it makes it easy to work with. You have the ability to start, stop, pause, change speed, etc. You can create animations that range from any frame to any frame and that can animate in many ways such as sequential (loop), play-once and ping-pong (back and forth, or rather the inverse). By making use of the time-lapse library we can easily create time-based animation.

The base code:

;##############################################################################
;$$$	file: Animation.pb - date: 05:05 p.m. 06/08/2009			$$$
;$$$	author: Gustavo Julio Fiorenza (info@gushh.net || info@gushh.com.ar)	$$$
;$$$					aka: gushh, dagcrack.			$$$
;$$$ 	description: provides several count modes for animation purposes	$$$
;##############################################################################
 
EnableExplicit
XIncludeFile "TimeLapse.pb" ; Used for timing.
 
Structure ANIMATION
	*timer.TIMELAPSE	; The timer's speed is "per frame", use the Get/SetLength functions to overcome this.
	frame_max.i		; Maximum global frame
	frame_min.i		; Minimum global frame
	frame_now.i		; Current local frame
	mode.i			; The animation mode (loop, play once, ping-pong, etc).
	status.i		; Internal var used for keeping track of the animation "status". It's used as a bool.
	is_playing.i		; Used to determine whether the animation is playing or not.
EndStructure
 
Enumeration 1
	#ANIMATION_LOOP
	#ANIMATION_PLAYONCE
	#ANIMATION_PINGPONG
EndEnumeration
 
 
Procedure.i AnimationCreate( Speed.i, MinFrame.i, MaxFrame.i, CurrentFrame.i = 0, Mode.i = #ANIMATION_LOOP, *callback.i = #Null )
 
	Define.ANIMATION *this = AllocateMemory( SizeOf(ANIMATION) )
 
	If *this
 
		With *this
			\timer		= TimeLapseCreate( Speed, *callback, *this ) ; We're passing this instance as the timer's user-data, useful in callbacks.
			\frame_max 	= MaxFrame
			\frame_min	= MinFrame
			\frame_now	= MinFrame + CurrentFrame
			\mode 		= Mode
			\status		= 0
			\is_playing	= #True
		EndWith
 
		ProcedureReturn *this
 
	EndIf
 
EndProcedure
 
Procedure.i AnimationDestroy( *this.ANIMATION )
 
	If *this
 
		If *this\timer
			TimeLapseDestroy(*this\timer)
		EndIf
 
		FreeMemory(*this)
		*this = #Null
		ProcedureReturn *this
 
	EndIf
 
EndProcedure
 
Procedure.i AnimationUpdate( *this.ANIMATION )
 
	If *this
		If *this\is_playing
			If TimeLapseUpdate( *this\timer )
 
				Select *this\mode
 
					Case #ANIMATION_LOOP
 
						*this\frame_now + 1
 
						If *this\frame_now > *this\frame_max
							*this\frame_now = *this\frame_min
						EndIf
 
					Case #ANIMATION_PINGPONG
 
						If *this\status
 
							*this\frame_now - 1
 
							If *this\frame_now < = *this\frame_min
								*this\status = #True - *this\status
							EndIf
 
						Else
 
							*this\frame_now + 1
 
							If *this\frame_now => *this\frame_max
								*this\status = #True - *this\status
							EndIf
 
						EndIf
 
					Case #ANIMATION_PLAYONCE
 
						If *this\status
							; status is set to one, this means we already played the animation.
						Else
 
							*this\frame_now + 1
 
							If *this\frame_now => *this\frame_max
								*this\status = #True - *this\status
							EndIf
 
						EndIf
 
				EndSelect	
 
				ProcedureReturn #True ; always return true unless you want to invalidate the update call!
 
			EndIf
		EndIf
	EndIf
 
EndProcedure

The helper functions:

Procedure.i AnimationGetCurrentFrame( *this.ANIMATION )
	ProcedureReturn *this\frame_now - *this\frame_min
EndProcedure
 
Procedure.i AnimationSetCurrentFrame( *this.ANIMATION, Frame.i )
	*this\frame_now = (Frame - *this\frame_min)
EndProcedure
 
Procedure.i AnimationGetTotalFrames( *this.ANIMATION )
	ProcedureReturn (*this\frame_max - *this\frame_min)
EndProcedure
 
Procedure.i AnimationGetMode( *this.ANIMATION )
	ProcedureReturn *this\mode
EndProcedure
 
Procedure.i AnimationSetMode( *this.ANIMATION, NewMode.i )
	*this\mode = NewMode
EndProcedure
 
Procedure.i AnimationGetSpeed( *this.ANIMATION )
	ProcedureReturn TimeLapseGet( *this\timer )
EndProcedure
 
Procedure.i AnimationSetSpeed( *this.ANIMATION, Speed.i )
	TimeLapseSet( *this\timer, Speed )
EndProcedure
 
Procedure.i AnimationPlay( *this.ANIMATION )
	*this\is_playing	= #True
EndProcedure
 
Procedure.i AnimationPause( *this.ANIMATION )
	*this\is_playing	= #False
EndProcedure
 
Procedure.i AnimationStop( *this.ANIMATION )
	*this\is_playing	= #False
	*this\frame_now		= *this\frame_min
EndProcedure
 
Procedure.i AnimationReset( *this.ANIMATION )
	AnimationStop(*this)
	AnimationPlay(*this)
EndProcedure
 
Procedure.i AnimationGetLength( *this.ANIMATION )
	ProcedureReturn AnimationGetTotalFrames( *this ) * AnimationGetSpeed( *this )
EndProcedure
 
Procedure.i AnimationSetLength( *this.ANIMATION, NewLength.i )
	AnimationSetSpeed( *this, NewLength / AnimationGetTotalFrames( *this ) )
EndProcedure

Thanks to the base lib, you can also use callbacks, this are useful for executing events on known frames (say you’re writing a game and you want a sound to be played at frame 12 from the jumping cycle… easy!)

A minimal example:

Define.ANIMATION *anim
 
If OpenConsole()
	*anim = AnimationCreate( 250, 0, 9, 0, #ANIMATION_PINGPONG )
	If *anim
		Repeat
			If AnimationUpdate( *anim ) ; the reason frame 0 is not seen in the first print is because we update before we display.
				PrintN( Str( AnimationGetCurrentFrame( *anim ) ) )
			EndIf
			Delay(10)
		Until Inkey() = Chr(27)
 
		AnimationDestroy(*anim)
	EndIf
	CloseConsole()
EndIf

A somewhat bloated example with callbacks can be found in here.

The playback functionality could be extended, however I found little need for other methods — That’s basically my excuse for “I ran out of ideas” — One thing I’d do is decouple the “play once” functionality from the playing mode, so essentially you’d be able to play a loop or ping-pong animation just once.

That’s pretty much it. Once again, this is trivial code but it’s a must and I’m sure someone will benefit from it.

The only reason I didn’t post a graphical example is because you need a way of dealing with sprite sheets and that’s the job for yet another library. Should you use the sprite library, you’d still need to feed the ClipSprite() function with meaningful data, there is no point in doing it by hand. That said, I’ll post the “sprite atlas” library tomorrow, hopefully.

Cheers

TimeLapse lib

GuShH — Wed, 05 Aug 2009 18:48:02 +0000

This little lib is used to keep track of time using the low resolution timer provided by the OS (in Windows “GetTickCount”). The goal of this type of library is to encapsulate timing actions. It was originally designed for game development in mind but needless to say you can use it and adapt it to your own needs.

Basically you define a time interval as you create the “timelapse” instance. Every time you call the update function a simple check determines whether the time was reached or not. This is trivial, but encapsulating it makes sense. Specially if you plan to create an animation system in the future!

The code:

EnableExplicit
 
Prototype.i TimeLapse_Callback( *this.i )
 
Structure TIMELAPSE
	old_time.i			; Stores the "old" time value.
	new_time.i			; Stores the "new" time value.
	time_out.i			; Time period for the TimeLapse , in ms.
	*callback.TimeLapse_Callback	; User callback.
	userdata.i			; User data.
EndStructure
 
CompilerSelect #PB_Compiler_OS
	CompilerCase #PB_OS_Windows
		Macro _time() : timeGetTime_()		: EndMacro
	CompilerDefault
		Macro _time() : ElapsedMilliseconds()	: EndMacro
CompilerEndSelect
 
Procedure.i TimeLapseCreate( Timeout.i, *Callback.TimeLapse_Callback = #Null, UserData.i = #Null )
 
	Define.TimeLapse  *this = AllocateMemory( SizeOf(TimeLapse ) )
 
	If *this
 
		With *this
			\new_time 	= _time()
			\old_time 	= *this\new_time
			\time_out	= Timeout
			\callback	= *Callback
			\userdata	= UserData
		EndWith
 
		ProcedureReturn *this
 
	EndIf
 
EndProcedure
 
Procedure.i TimeLapseDestroy( *this.TIMELAPSE  )
 
	If *this
 
		FreeMemory(*this)
		*this = #Null
		ProcedureReturn *this
 
	EndIf
 
EndProcedure
 
Procedure.i TimeLapseUpdate( *this.TIMELAPSE  )
 
	If *this
 
		*this\new_time = _time()
 
		If ((*this\new_time - *this\old_time) => *this\time_out)
 
			*this\old_time = *this\new_time
 
			If *this\callback
				ProcedureReturn *this\callback( *this )
			EndIf
 
			ProcedureReturn #True
 
		EndIf
 
	EndIf
 
EndProcedure
 
 
; Helper routines
 
Procedure.i TimeLapseSet( *this.TIMELAPSE , Timeout.i )
 
 	If Timeout > 0
		*this\time_out = Timeout
	EndIf
 
EndProcedure
 
Procedure.i TimeLapseGet( *this.TIMELAPSE  )
 
 	ProcedureReturn *this\time_out
 
EndProcedure

Example:

If OpenConsole()
	Define.TIMELAPSE  *test_timer  = TimeLapseCreate( 500 )
	Repeat
 
		If TimeLapseUpdate( *test_timer  )
			PrintN(" Timer says hi!" )
		EndIf
 
		Delay(10)
	Until Inkey() = Chr(27)
	CloseConsole()
EndIf
End

The nice thing about this library is the ability to use callbacks. Whenever a callback is defined, once the timer reaches the maximum allowed time-lapse, it’ll return by executing the callback.

In the callback you can do anything you want; From simple event triggering to manipulating another timer depending on XYZ conditions: it’s up to you!.

Just keep in mind: Always return “true” unless you want to invalidate the update call.

Here is a more advanced example with a callback, user data and multiple timers:

Procedure.i MyCallback( *this.TIMELAPSE  )
 
	; It's imperative that you return #true (1) in your callbacks if you want the "Update" calls to pass once the timeout is reached.
	; This is a design choice for flexibility and nothing else.
 
	ConsoleColor(Random(15), Random(15))
	PrintN(" Hi from the callback! ")
 
	PrintN( " The other timer is set to: " + Str( TimeLapseGet( *this\userdata ) ) + "ms" )
	PrintN( " ...Reducing the time interval down by 50 ms... " )
 
	TimeLapseSet( *this\userdata, TimeLapseGet( *this\userdata ) - 50 )
	ConsoleColor(15, 0)
 
	ProcedureReturn #True
 
EndProcedure
 
Define.TIMELAPSE  *timer_one 	= TimeLapseCreate( 500 )				; The first TimeLapse , nothing special.
Define.TIMELAPSE  *timer_two 	= TimeLapseCreate( 2000, @MyCallback(), *timer_one )	; The second TimeLapse , it manipulates the first one through a callback.
Define.TIMELAPSE  *timer_three	= TimeLapseCreate( 20*1000 )				; This TimeLapse  will simply let us exit the example after the set time.
 
If OpenConsole()
 
	EnableGraphicalConsole(1)
	ConsoleColor(15, 0)
 
	Define.i quit = #False
 
	Repeat
 
		If TimeLapseUpdate( *timer_three )
			quit = #True
		Else
			If TimeLapseUpdate( *timer_one )
				PrintN("timer_one: " + Str(*timer_one\time_out) + "ms reached.")
			EndIf
			If TimeLapseUpdate( *timer_two )
				PrintN("timer_two: " + Str(*timer_two\time_out) + "ms reached.")
			EndIf
		EndIf
 
		Delay(10)
 
	Until Inkey() = Chr(27) Or quit 
 
	PrintN( "timer_three: The example finished." )
 
	TimeLapseDestroy(*timer_one)
	TimeLapseDestroy(*timer_two)
	TimeLapseDestroy(*timer_three)
 
	Input()
	CloseConsole()
 
EndIf
End

The examples are crude, but they show every function in the library.
Should you have any questions, feel free to ask.

I’ll soon post the “Animation” lib that depends on “TimeLapse”.

Cheers.

GuShH's Development Blog » animation

Animation lib

Related Posts:

TimeLapse lib

Related Posts: