1libnsgif - Decoding GIF files 2============================= 3 4The functions provided by this library allow for efficient progressive 5GIF decoding. Whilst the initialisation does not ensure that there is 6sufficient image data to complete the entire frame, it does ensure 7that the information provided is valid. Any subsequent attempts to 8decode an initialised GIF are guaranteed to succeed, and any bytes of 9the image not present are assumed to be totally transparent. 10 11To begin decoding a GIF, the 'gif' structure must be initialised with 12the 'gif_data' and 'buffer_size' set to their initial values. The 13'buffer_position' should initially be 0, and will be internally 14updated as the decoding commences. The caller should then repeatedly 15call gif_initialise() with the structure until the function returns 1, 16or no more data is avaliable. 17 18Once the initialisation has begun, the decoder completes the variables 19'frame_count' and 'frame_count_partial'. The former being the total 20number of frames that have been successfully initialised, and the 21latter being the number of frames that a partial amount of data is 22available for. This assists the caller in managing the animation 23whilst decoding is continuing. 24 25To decode a frame, the caller must use gif_decode_frame() which 26updates the current 'frame_image' to reflect the desired frame. The 27required 'disposal_method' is also updated to reflect how the frame 28should be plotted. The caller must not assume that the current 29'frame_image' will be valid between calls if initialisation is still 30occuring, and should either always request that the frame is decoded 31(no processing will occur if the 'decoded_frame' has not been 32invalidated by initialisation) or perform the check itself. 33 34It should be noted that gif_finalise() should always be called, even 35if no frames were initialised. Additionally, it is the responsibility 36of the caller to free 'gif_data'. 37