diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 36 |
1 files changed, 36 insertions, 0 deletions
@@ -0,0 +1,36 @@ +libnsgif - Decoding GIF files +============================= + +The functions provided by this library allow for efficient progressive +GIF decoding. Whilst the initialisation does not ensure that there is +sufficient image data to complete the entire frame, it does ensure +that the information provided is valid. Any subsequent attempts to +decode an initialised GIF are guaranteed to succeed, and any bytes of +the image not present are assumed to be totally transparent. + +To begin decoding a GIF, the 'gif' structure must be initialised with +the 'gif_data' and 'buffer_size' set to their initial values. The +'buffer_position' should initially be 0, and will be internally +updated as the decoding commences. The caller should then repeatedly +call gif_initialise() with the structure until the function returns 1, +or no more data is avaliable. + +Once the initialisation has begun, the decoder completes the variables +'frame_count' and 'frame_count_partial'. The former being the total +number of frames that have been successfully initialised, and the +latter being the number of frames that a partial amount of data is +available for. This assists the caller in managing the animation +whilst decoding is continuing. + +To decode a frame, the caller must use gif_decode_frame() which +updates the current 'frame_image' to reflect the desired frame. The +required 'disposal_method' is also updated to reflect how the frame +should be plotted. The caller must not assume that the current +'frame_image' will be valid between calls if initialisation is still +occuring, and should either always request that the frame is decoded +(no processing will occur if the 'decoded_frame' has not been +invalidated by initialisation) or perform the check itself. + +It should be noted that gif_finalise() should always be called, even +if no frames were initialised. Additionally, it is the responsibility +of the caller to free 'gif_data'. |