GIFPlay.bas

'-----------------------------------------------------------------------------------------------------------------------
' Animated GIF Player library
' Copyright (c) 2024 Samuel Gomes
'-----------------------------------------------------------------------------------------------------------------------

$INCLUDEONCE

'$INCLUDE:'GIFPlay.bi'

'-------------------------------------------------------------------------------------------------------------------
' Test code for debugging the library
'-------------------------------------------------------------------------------------------------------------------
'$RESIZE:SMOOTH
'$CONSOLE

'DEFLNG A-Z
'OPTION _EXPLICIT

'CONST GIF_ID = 1

'DO
'    DIM gifFileName AS STRING: gifFileName = _OPENFILEDIALOG$("Open GIF", , "*.gif|*.GIF|*.Gif", "GIF Files")
'    IF LEN(gifFileName) = 0 THEN EXIT DO

'    IF GIF_LoadFromFile(GIF_ID, gifFileName) THEN
'        DIM surface AS LONG: surface = _NEWIMAGE(GIF_GetWidth(GIF_ID), GIF_GetHeight(GIF_ID), 32)
'        SCREEN surface
'        _ALLOWFULLSCREEN _SQUAREPIXELS , _SMOOTH

'        GIF_Play GIF_ID

'        DO
'            DIM k AS LONG: k = _KEYHIT

'            IF k = 32 THEN
'                IF GIF_IsPlaying(GIF_ID) THEN GIF_Pause (GIF_ID) ELSE GIF_Play (GIF_ID)
'            END IF

'            CLS
'            GIF_Draw GIF_ID
'            _DISPLAY

'            _LIMIT 30
'        LOOP UNTIL k = 27

'        SCREEN 0
'        _FREEIMAGE surface
'    END IF
'LOOP

'END
'-------------------------------------------------------------------------------------------------------------------

' Opens a GIF file from a buffer in memory
FUNCTION GIF_LoadFromMemory%% (Id AS LONG, buffer AS STRING)
    $IF INFORM_BI = DEFINED THEN
        IF Control(ID).Type <> __UI_Type_PictureBox THEN
        ERROR 5
        EXIT FUNCTION
        END IF
    $END IF

    DIM sf AS StringFileType

    StringFile_Create sf, buffer

    GIF_LoadFromMemory = __GIF_Load(Id, sf)
END FUNCTION


' Opens a GIF file from a file on disk
FUNCTION GIF_LoadFromFile%% (Id AS LONG, fileName AS STRING)
    $IF INFORM_BI = DEFINED THEN
        IF Control(ID).Type <> __UI_Type_PictureBox THEN
        ERROR 5
        EXIT FUNCTION
        END IF
    $END IF

    DIM sf AS StringFileType: StringFile_Create sf, File_Load(fileName)

    IF StringFile_GetSize(sf) THEN
        GIF_LoadFromFile = __GIF_Load(Id, sf)
    END IF
END FUNCTION


' Free a GIF and all associated resources
SUB GIF_Free (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType
    SHARED __GIFPlayFrame() AS __GIFPlayFrameType
    SHARED __GIF_FirstFreeFrame AS LONG

    ' Nothing to do if Id is invalid
    IF NOT HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN EXIT SUB

    ' Get the slot we need to free
    DIM idx AS LONG: idx = HashTable_LookupLong(__GIFPlayHashTable(), Id)

    ' Walk the whole animation chain to free all the frames and associated data
    __GIFPlay(idx).frame = __GIFPlay(idx).firstFrame

    DO
        ' Free the image being held by the frame
        IF __GIFPlayFrame(__GIFPlay(idx).frame).image < -1 THEN
            _FREEIMAGE __GIFPlayFrame(__GIFPlay(idx).frame).image
            __GIFPlayFrame(__GIFPlay(idx).frame).image = 0
        END IF

        ' Mark the frame slot as unused so that it can be reused
        __GIFPlayFrame(__GIFPlay(idx).frame).isUsed = _FALSE

        ' Note the lowest free frame
        IF __GIF_FirstFreeFrame > __GIFPlay(idx).frame THEN __GIF_FirstFreeFrame = __GIFPlay(idx).frame

        ' Move to the next frame
        __GIFPlay(idx).frame = __GIFPlayFrame(__GIFPlay(idx).frame).nextFrame
    LOOP UNTIL __GIFPlay(idx).frame = __GIFPlay(idx).firstFrame ' loop until we come back to the first frame

    ' Free the rendered image
    IF __GIFPlay(idx).image < -1 THEN
        _FREEIMAGE __GIFPlay(idx).image
        __GIFPlay(idx).image = 0
    END IF

    ' Free the saved rendered image
    IF __GIFPlay(idx).savedImage < -1 THEN
        _FREEIMAGE __GIFPlay(idx).savedImage
        __GIFPlay(idx).savedImage = 0
    END IF

    ' Finally mark the GIF slot as unused so that it can be reused
    __GIFPlay(idx).isUsed = _FALSE

    ' Remove Id from the hash table
    HashTable_Remove __GIFPlayHashTable(), Id
END SUB


' Returns the width of the animation in pixels
FUNCTION GIF_GetWidth~& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetWidth = _WIDTH(__GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).image)
    END IF
END FUNCTION


' Returns the height of the animation in pixels
FUNCTION GIF_GetHeight~& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetHeight = _HEIGHT(__GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).image)
    END IF
END FUNCTION


' Returns the number of currently playing frame
FUNCTION GIF_GetFrameNumber~& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetFrameNumber = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).frameNumber
    END IF
END FUNCTION


' Returns the total frames in the GIF. If this is 1 then it is a static image
FUNCTION GIF_GetTotalFrames~& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetTotalFrames = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).frameCount
    END IF
END FUNCTION


' Resume or starts playback
SUB GIF_Play (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        DIM idx AS LONG: idx = HashTable_LookupLong(__GIFPlayHashTable(), Id)

        __GIFPlay(idx).isPlaying = _TRUE
        __GIFPlay(idx).lastTick = Time_GetTicks
    END IF
END SUB


' Pauses playback. That same frame is served as long as playback is paused
SUB GIF_Pause (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).isPlaying = _FALSE
    END IF
END SUB


' Stops playing the GIF and resets the cursor to the first frame
SUB GIF_Stop (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        DIM idx AS LONG: idx = HashTable_LookupLong(__GIFPlayHashTable(), Id)

        __GIFPlay(idx).isPlaying = _FALSE
        __GIFPlay(idx).frame = __GIFPlay(idx).firstFrame
        __GIFPlay(idx).frameNumber = 0
        __GIFPlay(idx).loopCounter = 0
        __GIFPlay(idx).elapsedTime = 0
        __GIFPlay(idx).lastFrameRendered = -1
        __GIFPlay(idx).hasSavedImage = _FALSE
    END IF
END SUB


' Return True if GIF is currently playing
FUNCTION GIF_IsPlaying%% (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_IsPlaying = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).isPlaying
    END IF
END FUNCTION


' This draws the current frame on the destination surface @ (0, 0) (stretching the frame if needed)
' This will also draw the overlay if the playback is stopped / paused
SUB GIF_Draw (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        $IF INFORM_BI = DEFINED THEN
            BeginDraw ID
        $END IF

        ' Get the rendered image handle
        DIM renderedFrame AS LONG: renderedFrame = GIF_GetFrame(Id)

        ' Cache the GIF index because we'll be using this a lot
        DIM idx AS LONG: idx = HashTable_LookupLong(__GIFPlayHashTable(), Id)

        ' Clear the surface using the background color (this will be black if the GIF has no global color table)
        CLS , __GIFPlay(idx).bgColor

        ' Blit the rendered frame
        _PUTIMAGE , renderedFrame, , , _SMOOTH

        ' Render the overlay if needed
        IF NOT __GIFPlay(idx).isPlaying AND __GIFPlay(idx).overlayEnabled AND __GIFPlay(idx).frameCount > 1 THEN
            DIM overlayImage AS LONG: overlayImage = __GIF_GetOverlayImage

            _PUTIMAGE (_SHR(_WIDTH, 1) - _SHR(_WIDTH(overlayImage), 1), _SHR(_HEIGHT, 1) - _SHR(_HEIGHT(overlayImage), 1)), overlayImage
        END IF

        $IF INFORM_BI = DEFINED THEN
            EndDraw ID
        $END IF
    END IF
END SUB


' This returns the current rendered frame (QB64 image) to be played
' Playback is time sensitive so frames may be skipped or the last frame may be returned
' Use this if you want to do your own rendering
' Also do not free the image. The library will do that when it is no longer needed
FUNCTION GIF_GetFrame& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType
    SHARED __GIFPlayFrame() AS __GIFPlayFrameType

    ' Exit if Id is not valid
    IF NOT HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN EXIT FUNCTION

    ' Cache the GIF index because we'll be using this a lot
    DIM idx AS LONG: idx = HashTable_LookupLong(__GIFPlayHashTable(), Id)

    ' Always return the rendered image handle (since this does not change during the GIFs lifetime)
    GIF_GetFrame = __GIFPlay(idx).image

    ' Exit if we are paused or not ready
    IF NOT __GIFPlay(idx).isPlaying OR NOT __GIFPlay(idx).isReady THEN EXIT FUNCTION

    ' Exit if we finished a single or the specified number of loops
    IF __GIFPlay(idx).loops <> 0 AND (__GIFPlay(idx).loopCounter < 0 OR __GIFPlay(idx).loopCounter >= __GIFPlay(idx).loops) THEN EXIT FUNCTION

    ' Fetch and store the current tick
    DIM currentTick AS _UNSIGNED _INTEGER64: currentTick = Time_GetTicks

    ' Remember the last frame index
    DIM lastFrameRendered AS LONG: lastFrameRendered = __GIFPlay(idx).frame

    ' Walk through the animation chain and find the frame we have to render based on the tick we recorded the last time
    DO UNTIL currentTick < __GIFPlay(idx).lastTick + __GIFPlayFrame(__GIFPlay(idx).frame).duration
        ' Add the current frame duration to lastTick so that we can do frame skips if needed
        __GIFPlay(idx).lastTick = __GIFPlay(idx).lastTick + __GIFPlayFrame(__GIFPlay(idx).frame).duration
        ' Increment elapsed time
        __GIFPlay(idx).elapsedTime = __GIFPlay(idx).elapsedTime + __GIFPlayFrame(__GIFPlay(idx).frame).duration
        ' We crossed the duration of the current frame, so move to the next one
        __GIFPlay(idx).frame = __GIFPlayFrame(__GIFPlay(idx).frame).nextFrame ' this should correctly loop back to the first frame
        ' Increment the frame counter and loop back to 0 if needed
        __GIFPlay(idx).frameNumber = __GIFPlay(idx).frameNumber + 1
        IF __GIFPlay(idx).frameNumber >= __GIFPlay(idx).frameCount THEN
            __GIFPlay(idx).frameNumber = 0
            __GIFPlay(idx).loopCounter = __GIFPlay(idx).loopCounter + 1

            IF __GIFPlay(idx).loops < 0 THEN
                __GIFPlay(idx).loopCounter = -1 ' single-shot animation
            ELSE
                __GIFPlay(idx).elapsedTime = 0 ' only reset the elapsed time for looping playback
            END IF
        END IF
    LOOP

    ' If the last frame rendered is the same as the current frame then just return the previously rendered frame image
    IF __GIFPlay(idx).frame = __GIFPlay(idx).lastFrameRendered THEN EXIT FUNCTION

    ' We now have the frame to display, so save the currentTick and update lastFrameRendered
    __GIFPlay(idx).lastTick = currentTick
    __GIFPlay(idx).lastFrameRendered = lastFrameRendered

    ' Take appropriate action based on the disposal method of the previous frame
    IF __GIFPlay(idx).frame = __GIFPlay(idx).firstFrame THEN
        ' If this is the first frame, then we do not have any previous disposal method
        CLS , __GIFPlay(idx).bgColor, __GIFPlay(idx).image ' clear the render image using the BG color
    ELSE
        SELECT CASE __GIFPlayFrame(__GIFPlayFrame(__GIFPlay(idx).frame).prevFrame).disposalMethod
            CASE 2 ' Restore to background color
                CLS , __GIFPlay(idx).bgColor, __GIFPlay(idx).image
                _CLEARCOLOR __GIFPlay(idx).bgColor, __GIFPlay(idx).image

            CASE 3 ' Restore to previous
                IF __GIFPlay(idx).hasSavedImage THEN
                    ' Copy back the saved image and unset the flag
                    _PUTIMAGE , __GIFPlay(idx).savedImage, __GIFPlay(idx).image
                    __GIFPlay(idx).hasSavedImage = _FALSE
                END IF

                ' All other disposal methods do not require any action
        END SELECT
    END IF

    ' If the current frame's disposal method is 3 (restore to previous) then save the current rendered frame and set the flag
    IF __GIFPlayFrame(__GIFPlay(idx).frame).disposalMethod = 3 THEN
        _PUTIMAGE , __GIFPlay(idx).image, __GIFPlay(idx).savedImage
        __GIFPlay(idx).hasSavedImage = _TRUE
    END IF

    ' Render the frame at the correct (x, y) offset on the final image
    _PUTIMAGE (__GIFPlayFrame(__GIFPlay(idx).frame).L, __GIFPlayFrame(__GIFPlay(idx).frame).T), __GIFPlayFrame(__GIFPlay(idx).frame).image, __GIFPlay(idx).image
END FUNCTION


' Returns the background color that should be used to clear the surface before drawing the final rendered frame
FUNCTION GIF_GetBackgroundColor~& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetBackgroundColor = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).bgColor
    END IF
END FUNCTION


' Returns the total runtime of the animation in ms
FUNCTION GIF_GetTotalDuration~&& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetTotalDuration = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).duration
    END IF
END FUNCTION


' Returns the total runtime of the current frame in ms
FUNCTION GIF_GetFrameDuration~&& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType
    SHARED __GIFPlayFrame() AS __GIFPlayFrameType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetFrameDuration = __GIFPlayFrame(__GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).frame).duration
    END IF
END FUNCTION


' Returns the current runtime of the animation in ms
FUNCTION GIF_GetElapsedTime~&& (Id AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_GetElapsedTime = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).elapsedTime
    END IF
END FUNCTION


' Set the looping behavior
SUB GIF_SetLoop (Id AS LONG, loops AS LONG)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).loops = loops
    END IF
END SUB


' Sets the GIF overlay to enable / disable
SUB GIF_EnableOverlay (Id AS LONG, isEnabled AS _BYTE)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).overlayEnabled = isEnabled
    END IF
END SUB


' Returns TRUE if a GIF with Id is loaded
FUNCTION GIF_IsLoaded%% (Id AS LONG)
    $CHECKING:OFF
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType

    IF HashTable_IsKeyPresent(__GIFPlayHashTable(), Id) THEN
        GIF_IsLoaded = __GIFPlay(HashTable_LookupLong(__GIFPlayHashTable(), Id)).isReady
    END IF
    $CHECKING:ON
END FUNCTION


' Deinterlaces a raw GIF frame
SUB __GIF_DeinterlaceFrameImage (bmp AS LONG)
    DIM W AS LONG: W = _WIDTH(bmp)
    DIM H AS LONG: H = _HEIGHT(bmp)
    DIM MX AS LONG: MX = W - 1
    DIM n AS LONG: n = _NEWIMAGE(W, H, 256)

    DIM AS LONG y, i

    WHILE y < H
        _PUTIMAGE (0, y), bmp, n, (0, i)-(MX, i)
        i = i + 1
        y = y + 8
    WEND

    y = 4
    WHILE y < H
        _PUTIMAGE (0, y), bmp, n, (0, i)-(MX, i)
        i = i + 1
        y = y + 8
    WEND

    y = 2
    WHILE y < H
        _PUTIMAGE (0, y), bmp, n, (0, i)-(MX, i)
        i = i + 1
        y = y + 4
    WEND

    y = 1
    WHILE y < H
        _PUTIMAGE (0, y), bmp, n, (0, i)-(MX, i)
        i = i + 1
        y = y + 2
    WEND

    _PUTIMAGE , n, bmp
    _FREEIMAGE n
END SUB


' https://commandlinefanatic.com/cgi-bin/showarticle.cgi?article=art011
FUNCTION __GIF_ReadLZWCode& (sf AS StringFileType, buffer AS STRING, bitPos AS LONG, bitSize AS LONG)
    DIM AS LONG code, p: p = 1

    DIM i AS LONG: FOR i = 1 TO bitSize
        DIM bytePos AS LONG: bytePos = _SHR(bitPos, 3) AND 255

        IF bytePos = 0 THEN
            DIM dataLen AS LONG: dataLen = StringFile_ReadByte(sf)

            IF dataLen = 0 THEN
                __GIF_ReadLZWCode = -1
                EXIT FUNCTION
            END IF

            MID$(buffer, 257 - dataLen, dataLen) = StringFile_ReadString(sf, dataLen)

            bytePos = 256 - dataLen
            bitPos = _SHL(bytePos, 3)
        END IF

        IF ASC(buffer, 1 + bytePos) AND _SHL(1, bitPos AND 7) THEN code = code + p

        p = p + p
        bitPos = bitPos + 1
    NEXT i

    __GIF_ReadLZWCode = code
END FUNCTION


' https://stackoverflow.com/questions/26894809/gif-lzw-decompression
FUNCTION __GIF_DecodeLZW%% (sf AS StringFileType, bmpMem AS _MEM)
    TYPE __LZWCodeType
        c AS LONG
        prefix AS LONG
        length AS LONG
    END TYPE

    DIM codes(0 TO 4095) AS __LZWCodeType ' maximum bit size is 12

    DIM origBitSize AS LONG: origBitSize = StringFile_ReadByte(sf)
    DIM n AS LONG: n = 2 + _SHL(1, origBitSize)

    DIM i AS LONG: WHILE i < n
        codes(i).c = i
        codes(i).length = 0
        i = i + 1
    WEND

    DIM clearMarker AS LONG: clearMarker = n - 2
    DIM endMarker AS LONG: endMarker = n - 1

    DIM buffer AS STRING: buffer = SPACE$(256)
    DIM bitSize AS LONG: bitSize = origBitSize + 1
    DIM bitPos AS LONG

    ' Expect to read clear code as first code here
    DIM prev AS LONG: prev = __GIF_ReadLZWCode(sf, buffer, bitPos, bitSize)
    IF prev = -1 THEN EXIT FUNCTION

    DO
        DIM code AS LONG: code = __GIF_ReadLZWCode(sf, buffer, bitPos, bitSize)
        IF code = -1 THEN EXIT FUNCTION

        IF code = clearMarker THEN
            bitSize = origBitSize
            n = _SHL(1, bitSize) + 2
            bitSize = bitSize + 1
            prev = code
            _CONTINUE
        END IF

        IF code = endMarker THEN EXIT DO

        ' Known code: ok. Else: must be doubled char
        DIM c AS LONG: IF code < n THEN c = code ELSE c = prev

        ' Output the code
        DIM outPos AS LONG: outPos = outPos + codes(c).length

        i = 0
        DO
            _MEMPUT bmpMem, bmpMem.OFFSET + outPos - i, codes(c).c AS _UNSIGNED _BYTE

            IF codes(c).length <> 0 THEN
                c = codes(c).prefix
            ELSE
                EXIT DO
            END IF

            i = i + 1
        LOOP

        outPos = outPos + 1

        ' Unknown code -> must be double char
        IF code >= n THEN
            _MEMPUT bmpMem, bmpMem.OFFSET + outPos, codes(c).c AS _UNSIGNED _BYTE
            outPos = outPos + 1
        END IF

        ' Except after clear marker, build new code
        IF prev <> clearMarker AND n < 4096 THEN
            codes(n).prefix = prev
            codes(n).length = codes(prev).length + 1
            codes(n).c = codes(c).c
            n = n + 1
        END IF

        ' Out of bits? Increase
        IF _SHL(1, bitSize) = n THEN
            IF bitSize < 12 THEN bitSize = bitSize + 1
        END IF

        prev = code
    LOOP

    __GIF_DecodeLZW = _TRUE
END FUNCTION


' This applies the palette and transparency to a raw GIF frame image
' info - the GIF global and local frame data needed to prepare the frame image
' bmp - the raw frame image
SUB __GIF_PrepareFrameImage (info AS __GIFFrameType, bmp AS LONG)
    ' Set the 8-bit image palette
    DIM AS LONG x, y
    IF info.localColors = 0 THEN
        ' No local palette, so use the global one
        WHILE y < info.globalColors
            x = y * 3
            _PALETTECOLOR y, _RGB32(ASC(info.globalPalette, x + 1), ASC(info.globalPalette, x + 2), ASC(info.globalPalette, x + 3)), bmp
            y = y + 1
        WEND
    ELSE
        ' Use the local palette
        WHILE y < info.localColors
            x = y * 3
            _PALETTECOLOR y, _RGB32(ASC(info.localPalette, x + 1), ASC(info.localPalette, x + 2), ASC(info.localPalette, x + 3)), bmp
            y = y + 1
        WEND
    END IF

    ' Set the transparent color
    IF info.transparentColor >= 0 THEN _CLEARCOLOR info.transparentColor, bmp
END SUB


' This is an internal loading function common for both memory and file loaders
FUNCTION __GIF_Load%% (Id AS LONG, sf AS StringFileType)
    SHARED __GIFPlayHashTable() AS HashTableType
    SHARED __GIFPlay() AS __GIFPlayType
    SHARED __GIFPlayFrame() AS __GIFPlayFrameType
    SHARED __GIF_FirstFreeFrame AS LONG

    ' Check if Id already exists and if so free it
    IF GIF_IsLoaded(Id) THEN GIF_Free Id

    ' Check if we can read the signature at a minimum
    IF StringFile_GetSize(sf) < 6 THEN EXIT FUNCTION

    ' Check the file signature before proceeding further
    DIM buffer AS STRING: buffer = StringFile_ReadString(sf, 6)
    IF buffer <> "GIF87a" AND buffer <> "GIF89a" THEN EXIT FUNCTION

    ' Ok, so it is a GIF. Allocate resources to load the rest of the file
    DIM idx AS LONG: FOR idx = 0 TO UBOUND(__GIFPlay)
        IF NOT __GIFPlay(idx).isUsed THEN EXIT FOR
    NEXT idx

    ' No free GIF slots?
    IF idx > UBOUND(__GIFPlay) THEN REDIM _PRESERVE __GIFPlay(0 TO idx) AS __GIFPlayType

    __GIFPlay(idx).isUsed = _TRUE ' occupy the slot
    HashTable_InsertLong __GIFPlayHashTable(), Id, idx ' add it to the hash table

    ' Reset some stuff
    __GIFPlay(idx).isReady = _FALSE
    __GIFPlay(idx).firstFrame = -1
    __GIFPlay(idx).lastFrame = -1
    __GIFPlay(idx).frame = -1
    __GIFPlay(idx).frameCount = 0
    __GIFPlay(idx).frameNumber = 0
    __GIFPlay(idx).isPlaying = _FALSE
    __GIFPlay(idx).loops = 0
    __GIFPlay(idx).loopCounter = 0
    __GIFPlay(idx).duration = 0
    __GIFPlay(idx).lastTick = 0
    __GIFPlay(idx).elapsedTime = 0
    __GIFPlay(idx).lastFrameRendered = -1
    __GIFPlay(idx).hasSavedImage = _FALSE
    __GIFPlay(idx).overlayEnabled = _TRUE

    ' Get width and height
    DIM W AS _UNSIGNED INTEGER: W = StringFile_ReadInteger(sf)
    DIM H AS _UNSIGNED INTEGER: H = StringFile_ReadInteger(sf)

    ' Create the 32bpp rendered image using the width and height we got above
    __GIFPlay(idx).image = _NEWIMAGE(W, H, 32)
    __GIFPlay(idx).savedImage = _NEWIMAGE(W, H, 32)
    IF __GIFPlay(idx).image >= -1 OR __GIFPlay(idx).savedImage >= -1 THEN GOTO gif_load_error

    DIM i AS _UNSIGNED _BYTE: i = StringFile_ReadByte(sf)

    DIM rawFrame AS __GIFFrameType
    rawFrame.globalPalette = STRING$(768, 0)
    rawFrame.localPalette = STRING$(768, 0)
    rawFrame.transparentColor = -1 ' no transparent color

    ' Global color table?
    IF _READBIT(i, 7) THEN rawFrame.globalColors = _SHL(1, ((i AND 7) + 1))

    ' Background color is only valid with a global palette
    i = StringFile_ReadByte(sf)

    ' Skip aspect ratio
    StringFile_Seek sf, StringFile_GetPosition(sf) + 1

    ' Read the global palette data
    IF rawFrame.globalColors > 0 THEN MID$(rawFrame.globalPalette, 1, 3 * rawFrame.globalColors) = StringFile_ReadString(sf, 3 * rawFrame.globalColors)

    ' Get RGBA value from the global palette for the backgrond color
    __GIFPlay(idx).bgColor = _RGB32(ASC(rawFrame.globalPalette, i + 1), ASC(rawFrame.globalPalette, i + 2), ASC(rawFrame.globalPalette, i + 3))

    DIM frameIdx AS LONG: frameIdx = -1

    DO
        i = StringFile_ReadByte(sf)

        SELECT CASE i
            CASE &H2C ' image descriptor
                ' Look for a free slot from the last lowest freed index
                FOR frameIdx = __GIF_FirstFreeFrame TO UBOUND(__GIFPlayFrame)
                    IF NOT __GIFPlayFrame(frameIdx).isUsed THEN
                        __GIF_FirstFreeFrame = frameIdx + 1
                        EXIT FOR
                    END IF
                NEXT

                IF frameIdx > UBOUND(__GIFPlayFrame) THEN
                    ' Search from the beginning
                    FOR frameIdx = 0 TO UBOUND(__GIFPlayFrame)
                        IF NOT __GIFPlayFrame(frameIdx).isUsed THEN EXIT FOR
                    NEXT
                END IF

                ' If still no free frame slot then allocate one
                IF frameIdx > UBOUND(__GIFPlayFrame) THEN REDIM _PRESERVE __GIFPlayFrame(0 TO frameIdx) AS __GIFPlayFrameType

                ' Occupy the slot
                __GIFPlayFrame(frameIdx).isUsed = _TRUE

                ' Read frame size and offset
                __GIFPlayFrame(frameIdx).L = StringFile_ReadInteger(sf)
                __GIFPlayFrame(frameIdx).T = StringFile_ReadInteger(sf)
                W = StringFile_ReadInteger(sf)
                H = StringFile_ReadInteger(sf)

                ' Create a raw frame image from the width and height we got above
                __GIFPlayFrame(frameIdx).image = _NEWIMAGE(W, H, 256)
                IF __GIFPlayFrame(frameIdx).image >= -1 THEN GOTO gif_load_error

                i = StringFile_ReadByte(sf)

                ' Local palette?
                IF _READBIT(i, 7) THEN
                    rawFrame.localColors = _SHL(1, ((i AND 7) + 1))
                    MID$(rawFrame.localPalette, 1, 3 * rawFrame.localColors) = StringFile_ReadString(sf, 3 * rawFrame.localColors)
                END IF

                ' Decode the frame bitmap data
                DIM mI AS _MEM: mI = _MEMIMAGE(__GIFPlayFrame(frameIdx).image)
                IF mI.SIZE = 0 THEN GOTO gif_load_error

                IF NOT __GIF_DecodeLZW(sf, mI) THEN
                    _MEMFREE mI
                    GOTO gif_load_error
                END IF

                _MEMFREE mI

                ' De-interlace the bitmap if it is interlaced
                IF _READBIT(i, 6) THEN __GIF_DeinterlaceFrameImage __GIFPlayFrame(frameIdx).image

                ' Apply palette and transparency
                __GIF_PrepareFrameImage rawFrame, __GIFPlayFrame(frameIdx).image

                ' Update GIF properties
                IF __GIFPlay(idx).firstFrame = -1 THEN
                    ' This is the first frame of the animation
                    __GIFPlay(idx).firstFrame = frameIdx
                    __GIFPlay(idx).frame = frameIdx ' the starting frame
                    __GIFPlayFrame(frameIdx).prevFrame = frameIdx ' make previous frame to point to this
                    __GIFPlayFrame(frameIdx).nextFrame = frameIdx ' make next frame to point to this
                ELSE
                    ' This is not the first frame
                    __GIFPlayFrame(__GIFPlay(idx).firstFrame).prevFrame = frameIdx ' update first frame's previous frame
                    __GIFPlayFrame(__GIFPlay(idx).lastFrame).nextFrame = frameIdx ' udpate last frames's next frame
                    __GIFPlayFrame(frameIdx).prevFrame = __GIFPlay(idx).lastFrame ' previous frame is the last frame
                    __GIFPlayFrame(frameIdx).nextFrame = __GIFPlay(idx).firstFrame ' next frame is the the first frame

                END IF
                __GIFPlay(idx).lastFrame = frameIdx ' make the last frame to point to this
                __GIFPlayFrame(frameIdx).disposalMethod = rawFrame.disposalMethod
                IF rawFrame.duration = 0 THEN rawFrame.duration = 10~% ' 0.1 seconds if no duration is specified (this behavior is from the erstwhile GIFPlay library)
                __GIFPlayFrame(frameIdx).duration = 10~&& * rawFrame.duration ' convert to ticks (ms)
                __GIFPlay(idx).duration = __GIFPlay(idx).duration + __GIFPlayFrame(frameIdx).duration ' add the frame duration to the global duration
                __GIFPlay(idx).frameCount = __GIFPlay(idx).frameCount + 1

                ' Prepare for next frame
                rawFrame.localColors = 0
                rawFrame.localPalette = STRING$(768, 0)
                rawFrame.disposalMethod = 0
                rawFrame.transparentColor = -1 ' no transparent color
                rawFrame.duration = 0

            CASE &H21 ' extension introducer
                DIM j AS _UNSIGNED _BYTE: j = StringFile_ReadByte(sf) ' extension type
                i = StringFile_ReadByte(sf) ' size

                IF j = &HF9 THEN ' graphic control extension
                    ' Size must be 4
                    IF i <> 4 THEN GOTO gif_load_error

                    i = StringFile_ReadByte(sf)

                    rawFrame.disposalMethod = _SHR(i, 2) AND 7
                    rawFrame.duration = StringFile_ReadInteger(sf)

                    IF _READBIT(i, 0) THEN ' transparency?
                        rawFrame.transparentColor = StringFile_ReadByte(sf)
                    ELSE
                        StringFile_Seek sf, StringFile_GetPosition(sf) + 1
                    END IF

                    i = StringFile_ReadByte(sf) ' size
                ELSEIF j = &HFF THEN ' application extension
                    IF i = 11 THEN
                        buffer = StringFile_ReadString(sf, 11)
                        i = StringFile_ReadByte(sf) ' size
                        IF _STRCMP(buffer, "NETSCAPE2.0") = 0 THEN
                            IF i = 3 THEN
                                j = StringFile_ReadByte(sf)
                                __GIFPlay(idx).loops = StringFile_ReadInteger(sf)
                                IF j <> 1 THEN __GIFPlay(idx).loops = 0
                                i = StringFile_ReadByte(sf) ' size
                            END IF
                        END IF
                    END IF
                END IF

                ' Possibly more blocks until terminator block (0)
                WHILE i > 0
                    StringFile_Seek sf, StringFile_GetPosition(sf) + i
                    i = StringFile_ReadByte(sf)
                WEND

            CASE &H3B ' GIF trailer
                EXIT DO
        END SELECT
    LOOP WHILE NOT StringFile_IsEOF(sf)

    ' Bad / corrupt GIF?
    IF __GIFPlay(idx).frameCount = 0 THEN GOTO gif_load_error

    '__GIF_PrintDebugInfo idx

    __GIFPlay(idx).isReady = _TRUE ' set the ready flag

    ' Render the first frame and then stop
    GIF_Play Id
    DIM dummy AS LONG: dummy = GIF_GetFrame(Id)
    GIF_Stop Id

    __GIF_Load = _TRUE
    EXIT FUNCTION

    gif_load_error:
    GIF_Free Id ' use GIF_Free() to cleanup if we encountered any error
END FUNCTION


'SUB __GIF_PrintDebugInfo (index AS LONG)
'    SHARED __GIFPlay() AS __GIFPlayType
'    SHARED __GIFPlayFrame() AS __GIFPlayFrameType

'    _ECHO "Dump for GIF:" + STR$(index) + CHR$(10)

'    _ECHO "isUsed =" + STR$(__GIFPlay(index).isUsed)
'    _ECHO "image =" + STR$(__GIFPlay(index).image)
'    _ECHO "bgColor =" + STR$(__GIFPlay(index).bgColor)
'    _ECHO "firstFrame =" + STR$(__GIFPlay(index).firstFrame)
'    _ECHO "lastFrame =" + STR$(__GIFPlay(index).lastFrame)
'    _ECHO "frame =" + STR$(__GIFPlay(index).frame)
'    _ECHO "frameCount =" + STR$(__GIFPlay(index).frameCount)
'    _ECHO "frameNumber =" + STR$(__GIFPlay(index).frameNumber)
'    _ECHO "isPlaying =" + STR$(__GIFPlay(index).isPlaying)
'    _ECHO "loops =" + STR$(__GIFPlay(index).loops)
'    _ECHO "loopCounter =" + STR$(__GIFPlay(index).loopCounter)
'    _ECHO "duration =" + STR$(__GIFPlay(index).duration)
'    _ECHO "lastTick =" + STR$(__GIFPlay(index).lastTick)
'    _ECHO "lastFrameRendered =" + STR$(__GIFPlay(index).lastFrameRendered)
'    _ECHO "savedImage =" + STR$(__GIFPlay(index).savedImage)
'    _ECHO "hasSavedImage =" + STR$(__GIFPlay(index).hasSavedImage)
'    _ECHO "overlayEnabled =" + STR$(__GIFPlay(index).overlayEnabled)

'    _ECHO CHR$(10) + "Walking animation chain..." + CHR$(10)

'    DO
'        _ECHO "Dump for frame:" + STR$(__GIFPlay(index).frame) + CHR$(10)

'        _ECHO "isUsed =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).isUsed)
'        _ECHO "prevFrame =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).prevFrame)
'        _ECHO "nextFrame =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).nextFrame)
'        _ECHO "image =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).image)
'        _ECHO "L =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).L)
'        _ECHO "T =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).T)
'        _ECHO "disposalMethod =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).disposalMethod)
'        _ECHO "duration =" + STR$(__GIFPlayFrame(__GIFPlay(index).frame).duration)

'        _ECHO CHR$(10) + "Changing to next frame..."
'        __GIFPlay(index).frame = __GIFPlayFrame(__GIFPlay(index).frame).nextFrame
'    LOOP UNTIL __GIFPlay(index).frame = __GIFPlay(index).firstFrame
'END SUB


' This gets the GIF overlay image (real loading only happens once)
FUNCTION __GIF_GetOverlayImage&
    CONST SIZE_GIFOVERLAYIMAGE_BMP_16506~& = 16506~&
    CONST COMP_GIFOVERLAYIMAGE_BMP_16506%% = -1%%
    CONST DATA_GIFOVERLAYIMAGE_BMP_16506 = _
        "eNpy8q1yYACDKiDOAWIHKGZkUGBgZsAF/kMQjDM4gRSgfbsGjt+I4jgexj+2YU57nd27H0Nl6htD6wkzJ31hqFyFWkMVZmZm5rzjMyjfzcwLvEKj" + _
        "tXTnFbyZjxn0O60WBBjDdVjDU/gAP0LwK77CW3gKa7gOY+B3c1k13Ic3ICm9gftQQ8h1BIt4GdInL2MRRxBKHcd1+BIyIF/iehzHYdWpmMXnkEPy" + _
        "OWZxKgZZV2AbEohtXI5B1Di+hQTmW4z3ub3fBQncXX04Hs7CKiQnVnFWhtkfh+TM4zgrgza/AsmplZTHwh2QnLszRT8vheA/LlyObyAF8Q0u9zjm" + _
        "tyEFs52wL5iFFNRsgrXMZ5CC+gwnY/JfBym462LW719BCu4rHIGtRUhJLNo+H29ASuINMxYMQ1JooIUOekYHLTQgFpromJ8V1NFGV7+HOiQjw9C6" + _
        "L0VumzlOB02TvWehhTZ6VoavwX3QehXixWz7ysrK7rPPPrsXmXJfc98zGdqoa8bNzc2/f++tt97a19dJ9/tPP/20H1EPPfSQ/o0mJAOvwdVFabK7" + _
        "bFHCeuSRR/ZMWxh4fuMiTBygzff+u9267XY/X3vttT33Nc3gyn08NTW1474fQP4J3ATx0LH7/eabbzbt24D7mUajEWmWQPLfhHXffT8yMrJjs6Nr" + _
        "+3k00LZZAsq/jqcgCbX+u+8/++yzfc2OOgR1bSNWgPmfwoe+bd/ljig93tGCOLrd/ctvwM4dPLyL7yAJ9Rxt+/Pz8ztmnzTRc1+PYirT/Ibna/AF" + _
        "5KD56Qc0f72v+ROU+V1J6JeM89v2Hy+A/Inav8mm45ht/7b/i9FBPZD2n0X/107ye0YnhP4vzfjnti3BuqShc0FdC7iPQxn/fOc/msX2ZTr/Qd2u" + _
        "be2cIaD5/3oW81/tByzl5vsRZecM2R//3ucJbsLYQdc/bnv/u8616wCX2635Isrse6eRYX6r67H+uRDiqYWeo/mSjE8cN6aPzm78i5mTxbkIrl5J" + _
        "8xroOlfHBbvmN+2iAwkg/6vQuhfixfRvCWj/KN7nv/x1Pc9/DfX5/GcD9ZTnP5Fp/zdkzn+/Xsrz39X1D63z8SWk4L7Eker6Z2mvfx9HXM2U+P4H" + _
        "HQu2IAVDJrIlq8uKd/8TmfxqrMT3v2ndBsm526v7X6v7n6v736vnH6rnX6rnnzI+HmYCeP5tBqeW8PnH63A8wOdfX4L0yUvm+ddQq4a78QokpVdw" + _
        "N2rIY+nz70tYxZN431x3/g7v40msYmlQz7//BcxY2A4="

    STATIC overlayImage AS LONG

    ' Only do this once
    IF overlayImage = 0 THEN
        overlayImage = _LOADIMAGE(Base64_LoadResourceString(DATA_GIFOVERLAYIMAGE_BMP_16506, SIZE_GIFOVERLAYIMAGE_BMP_16506, COMP_GIFOVERLAYIMAGE_BMP_16506), 32, "memory")
    END IF

    __GIF_GetOverlayImage = overlayImage
END FUNCTION

'$INCLUDE:'HashTable.bas'
'$INCLUDE:'StringFile.bas'
'$INCLUDE:'Base64.bas'
'$INCLUDE:'File.bas'