The following image formats are known, but some depend on external libraries for the proper loading of files (indicated with * in the list): PNG*, JPEG*, TIFF*, GIF, XPM, PNM, Sun raster file (ras), ico, bmp.
With this package, you can load images from file, display them on the screen, re-scale them and compose them with other images. All the functions fully support alpha channels (opacity).
Different filters are provided, depending on the quality of output you expect and the speed you need.
For an explanation of dither offsets, see the Gdk.RGB documentation. In brief, the dither offset is important when re-rendering partial regions of an image to a rendered version of the full image, or for when the offsets to a base position change, as in scrolling. The dither matrix has to be shifted for consistent visual results. If you do not have any of these cases, the dither offsets can be both zero.
If the image does have opacity information and Alpha_Mode is Alpha_Bilevel, specifies the threshold value for opacity values
If the drawable src is a pixmap, then a suitable colormap must be specified, since pixmaps are just blocks of pixel data without an associated colormap. If the drawable is a window, the Cmap argument will be ignored and the window's own colormap will be used instead.
If the specified destination pixbuf Dest is Null_Pixbuf, then this function will create an RGB pixbuf with 8 bits per channel and no alpha, with the same size specified by the Width and Height arguments. In this case, the Dest_x and Dest_y arguments must be specified as 0, otherwise the function will return Null_Pixbuf. If the specified destination pixbuf is not Null_Pixbuf and it contains alpha information, then the filled pixels will be set to full opacity.
If the specified drawable is a pixmap, then the requested source rectangle must be completely contained within the pixmap, otherwise the function will return Null_Pixbuf.
If the specified drawable is a window, then it must be viewable, i.e. all of its ancestors up to the root window must be mapped. Also, the specified source rectangle must be completely contained within the window and within the screen. If regions of the window are obscured by non-inferior windows, the contents of those regions are undefined. The contents of regions obscured by inferior windows of a different depth than that of the source window will also be undefined.
Return value: The same pixbuf as Dest if it was non-NULL, or a newly-created pixbuf with a reference count of 1 if no destination pixbuf was specified.
Start_Time would normally come from G_Get_Current_Time, and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by Get_Pixbuf. Then, you should install a timeout (with Timeout_Add) or by some other mechanism to ensure that you'll update the image after Get_Delay_Time milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time.
As a shortcut, if Start_Time is equal to null, the result of G_Get_Current_Time will be used automatically.
To update the image (i.e. possibly change the result of Get_Pixbuf to a new frame of the animation), call Advance.
If you're using Gdk_Pixbuf_Loader, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and On_Currently_Loading_Frame returns True. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal.
A delay time of -1 is possible, indicating "infinite."
Current_Time would normally come from G_Get_Current_Time, and must be greater than or equal to the time passed to Get_Iter, and must increase or remain unchanged each time Get_Pixbuf is called. That is, you can't go backward in time; animations only play forward.
As a shortcut, pass null for the current time and G_Get_Current_Time will be invoked on your behalf. So you only need to explicitly pass Current_Time if you're doing something odd like playing the animation at double speed.
If this function returns False, there's no need to update the animation display, assuming the display had been rendered prior to advancing; if True, you need to call Get_Pixbuf and update the display with the new pixbuf.