February 2001, --Jcid
------
IMAGES
------
* When a image tag is found within a HTML page, Html_tag_open_img
handles it by:
- Parsing & getting attribute values.
- Creating a new image structure (DilloImage) and its
associated widget (DwImage).
i.e. If 'Image' is the var for the structure, then
'Image->dw' is the widget.
- Requesting the image to be feeded by the cache.
- Sending some info to the browser interface.
* The cache can either request the image data from the net, or
feed it directly from the dicache (decompressed image cache).
* Both processes are somewhat different because the first one
requires to decode the image data into RGB format, and the second
one has the whole data already decoded.
* Regardless of the RGB-data feeding method, the decoded data is
passed to the widget (DwImage) and drawn by GdkRGB in a streamed
way.
Note that INDEXED images are also decoded into RGB format
before sending them to GdkRGB.
---------------------
Fetching from the net
---------------------
* a_Cache_open_url initiates the resource request, and when
finally the answer arrives, the HTTP header is examined for MIME
type and either the GIF or PNG or JPEG decoder is set to handle
the incoming data stream.
Decoding functions: a_Gif_image, a_Jpeg_image and a_Png_image.
* The decoding function calls the following dicache methods as
the data is processed (listed in order):
a_Dicache_set_parms
a_Dicache_set_cmap (only for indexed-GIF images)
a_Dicache_write
a_Dicache_close
* The dicache methods call the necessary functions to connect
with the widget code. This is done by calling image.c functions:
a_Image_set_parms
a_Image_set_cmap
a_Image_write
a_Image_close
* The functions in image.c make the required a_Dw_image_...
calls.
-------------------------
Fetching from the dicache
-------------------------
* a_Cache_open_url tests the dicache for the image, and directly
enqueues a cache client for it, without asking the network for
the data. When the client queue is processed (a bit later), the
decoder is selected based on the cache entry type.
* When the decoder is called, it tests the dicache for the image;
if the image is found, then it sets a_Dicache_callback as the
handling function and gets out of the way (no image decoding is
needed).
* Later on, the DwImage buffer is set to reference the
dicache-entry's buffer and the rest of the functions calls is
driven by a_Dicache_callback.
-----------
Misc. notes
-----------
* Repeated images generate new cache clients, but only one of
them (the first) is handled with a_Dicache_* functions, the rest
is done with a_Dicache_callback..
* The cache-client callback is set when the Content-type of the
image is got. It can be: a_Png_image, a_Gif_image or a_Jpeg_image
Those are called 'decoders' because their main function is to
translate the original data into RGB format.
* Later on, the decoder can substitute itself, if it finds the
image has been already decoded, with a_Dicache_callback function.
This avoids decoding it twice.
* The dicache-entry and the Image structure hold bit arrays that
represent which rows had been decoded.
* The image processing can be found in the following sources:
- image.[ch]
- dicache.[ch]
- gif.[ch], png.[ch], jpeg.[ch]
- dw_image.[ch]
* Bear in mind that there are three data structures for image
code:
- DilloImage (image.h)
- DwImage (dw_image.h)
- DICacheEntry (dicache.h)