//
//------------------ DOK FILE --------------------------------------------------
+Header	core.2d.gif
=pkg	core.2d.gif
=title	core.2d.gif
=short	decoding GIF files (still or animated)
=desc
This package can decode gif files, including animated gifs.

The following example demonstrates how to read an animated 256x256 gif file "test.gif" and how to animate it on the screen.
The animation stops when the user clicks on the UI window.

	use core.2d.gif;;
	const SRC="test.gif";;
	
	var KeepGoing=true;;
	
	fun main()=
		uiStart( 10, 10, 256, 256, UI_NORMAL, "gif player - demo");
		uiOnClick (lambda (x y b)= set KeepGoing=false);
		let framesFromGif (load (SRC)) -> frames in
		gifAnimate (frames (lambda (frame)=
			bitmapBlit (uiBuffer(), 0, 0, frame, 0, 0, nil, nil, nil);
			uiUpdate();
			KeepGoing
		));;
//
//
//------------------ PROTO ----------------------------------------------------- bitmapFromGif
+Proto	bitmapFromGif
=type	fun Str -> Bitmap
=mode	function
=pkg	core.2d.gif
=impl	mcy
=link	
=desc
This function decodes a binary string with the GIF format and returns a [[Bitmap]], or nil when the input string has a wrong format.
When the gif is animated, it returns the last frame of the animation.
//
+arg	src
=type	Str
=desc	A binary string
//
+arg	result
=type	Bitmap
=desc	A bitmap
//
//
//------------------ PROTO ----------------------------------------------------- framesFromGif
+Proto	framesFromGif
=type	fun Str -> array [Bitmap Int]
=mode	function
=pkg	core.2d.gif
=impl	mcy
=link	
=desc
This function decodes a binary string with the GIF format and returns an array of tuples.
Each tuple contains a frame: a [[Bitmap]] and a duration (in milliseconds) of the frame before the next frame.
See [[gifAnimate]] to help rendering the animation.
//
+arg	src
=type	Str
=desc	A binary string
//
+arg	result
=type	array [Bitmap Int]
=desc	An array of tuples containing a Bitmap and a duration.
//
//
//------------------ PROTO ----------------------------------------------------- gifAnimate
+Proto	gifAnimate
=type	fun array [a1 Int] (fun a1 -> Bool) -> Bool
=mode	function
=pkg	core.2d.gif
=impl	mcy
=link	
=desc
This function should be used with [[framesFromGif]]. It "plays" the animation and calls the fRender function at the right time with the frame bitmap to display. It continues until fRender returns false or nil.
Note the type 'a1' instead of [[Bitmap]]: this function does not care about the type of the first element of the tuples. It just pass it to fRender.
//
+arg	frames
=type	array [a1 Int]
=desc	An array of tuples containing a Bitmap and a duration.
//
+arg	fRender
=type	fun a1 -> Bool
=desc	A lambda function which takes a Bitmap and returns true to continue the animation.
//
+arg	result
=type	Bool
=desc	Always true