path: root/README
diff options
authorVincent Sanders <>2017-01-24 23:49:34 +0000
committerVincent Sanders <>2017-01-24 23:49:34 +0000
commit33981c486fc6b660ee1ad8c48a38b2028c2b716e (patch)
tree33448088587689837d6ba9ae7b444620243c066a /README
parent944ea7acb8c8e894b84f4c9545cd93339c23c350 (diff)
Add doxygen config and update formatting and doc comments
Diffstat (limited to 'README')
1 files changed, 36 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..498ee46
--- /dev/null
+++ b/README
@@ -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'.