You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1548 lines
66 KiB
1548 lines
66 KiB
<html>
|
|
<head><title>
|
|
Imlib Programmers Guide
|
|
</title></head>
|
|
<body
|
|
background=bg.gif
|
|
bgcolor=#c0c0b0
|
|
text=#000000
|
|
link=#0000aa
|
|
vlink=#000088
|
|
alink=#ffff00
|
|
>
|
|
<font face=helvetica size=3>
|
|
<center><img src=imlib.gif alt="Imlib"></center>
|
|
<center><b><font color=#ffffff size=6>The Imlib Programmers Guide</font></b></center>
|
|
<p>
|
|
<b>What is Imlib?</b><br>
|
|
Imlib is a general Image loading and rendering library designed to make the
|
|
task of loading images, and obtaining X-Windows drawables a simple task, as
|
|
well as a quick one. It also aims to provide simple manipulation routines
|
|
that might be desired for common operations.
|
|
<p>
|
|
<b>Why use Imlib?</b><br>
|
|
Imlib is display depth independent. It will load images and work in 24 bit
|
|
internally, dithering, re-mapping or whatever is needed to generate X
|
|
drawables ready for use on the display by programs. It can also handle
|
|
rescaling images to different sizes very quickly, is configurable to be
|
|
"kind" to the colormap on 8-bit displays, generate transparencies, load more
|
|
than one image format (in fact Imlib will load any image format), and handle
|
|
intelligent caching for naive programs.
|
|
<p>
|
|
<b>So what are its features?</b><br>
|
|
<ul>
|
|
<li>
|
|
If compiled fully, Imlib can, without the help of any other applications,
|
|
load PPM, PGM, TIFF, PNG, XPM, JPEG and EIM format images and preserve their
|
|
transparency characteristics. If Imlib does not natively (native and foreign
|
|
formats will be discussed later), Imlib can call upon a set of tools on the
|
|
system to convert the image into a format Imlib can understand - thus
|
|
widening its range of formats to any format that another utility supports.
|
|
Currently Imlib supports both Imagemagick and the PBMPLUS utilities to do
|
|
this. This loading is slower, but it means that Imlib does not refuse to
|
|
load an image just because it does not know its format.
|
|
<li>
|
|
Imlib has image caches that allow the programmer to write naive code.
|
|
Images are loaded and cached. If an image is in the cache, it will not be
|
|
loaded again, but merely referenced from the cache. This can make naive
|
|
programs work surprisingly fast.
|
|
<li>
|
|
Imlib can rescale an image to any size (limit 32767 x 32767 pixels). This
|
|
means small icons can be expanded in size via Imlib, or large images reduced
|
|
to small thumbnails with a single function call.
|
|
<li>
|
|
Imlib has the ability to do gamma, brightness, contrast or arbitrary curve
|
|
mapping of images to improve their visibility, or to modify their appearance.
|
|
This allows for gamma correction, white-point correction and other advanced
|
|
features all in software, without any need for this in hardware. It also
|
|
allows the use of greyscale image templates to have their R, G and B
|
|
channels modified via mapping tables to be colorized. This can allow for
|
|
interfaces to use greyscale templates and let the user modify the color
|
|
mapping for a color scheme.
|
|
<li>
|
|
Imlib can do basic Image modifications (flip and rotate by 90 degrees),
|
|
which may be desired.
|
|
<li>
|
|
Imlib is highly optimized to give best results wherever possible at high
|
|
speeds. It has many options to hike up its rendering speed depending on what
|
|
your X Server and hardware setup can handle.
|
|
<li>
|
|
Imlib handles many display depths. It will work on monochrome, 2, 3, 4 ,5 ,6
|
|
7, and 8 bit pseudocolor and static color displays. It also works in 15 bit,
|
|
16 bit (555 and 565) displays, and 24 bit displays. If the display is
|
|
pseudocolor, Imlib will remap the image to a palette. Imlib has a config
|
|
file - a system and a user one - the user one taking preference over the
|
|
system config. In this The user, or system administrator defines a palette
|
|
file for Imlib to use. This file is a list of red , green and blue values to
|
|
be used as a color set for Imlib to map to in pseudocolor. This list can be
|
|
as large, or as small as desired (from 2 to 256 entries). By default Imlib
|
|
comes with a table of about 40 entries, specifically chosen to contain
|
|
colors commonly used in images and displays, rather than the more simplistic
|
|
colorcube approach. This file can be edited, with entries taken
|
|
out or added as desired. Imlib by default will dither using this colorset,
|
|
if in 8 bit or less. It does not allocate a private colormap, but merely
|
|
takes what colors it can get and compensates for this. Dithering can be
|
|
turned off if it is not desired, or if extra speed is needed. Imlib will
|
|
also seamlessly handle 15, 16 and 24 bits (with an optional High Quality
|
|
mode for 15 and 16 bpp where Imlib will even dither in these modes to make
|
|
smooth gradients look perfectly smooth). The end result is that images look
|
|
as best they can, and also preserve colormaps, in all bit depths.
|
|
<li>
|
|
When re-rendering an image at different sizes, Imlib has an advanced pixmap
|
|
cache that will re-use cached pixmaps if already rendered at that size,
|
|
speeding up rendering for native programs by saving the extra rendering into a
|
|
pixmap.
|
|
<il>
|
|
Imlib has support for the MIT-SHM extension via shared images to speed up
|
|
rendering. It also has support for the MIT-SHM shared pixmap extension, but
|
|
is unable to practically use this due to some major design flaws in the
|
|
shared pixmap extension. The support is there waiting for the day
|
|
when this is fixed.
|
|
<li>
|
|
Imlib has both Xlib and GDK versions that can be installed simultaneously,
|
|
share the same config file, and so can be used in both the Xlib low level
|
|
environment and the GDK level environment.
|
|
</ul>
|
|
<p>
|
|
<b>How do I start programming using Imlib?</b><br>
|
|
I suppose the best way to help you start using Imlib, is a small sample
|
|
program. Here are two - one using GDK, another using Xlib. (I will point out
|
|
that Xlib is more powerful than GDK - unlike GDK, an Xlib program can run on
|
|
multiple displays, and Imlib supports this - you just have to initialize
|
|
Imlib per display you connect to).
|
|
<p>
|
|
The following program is a very simple image viewer. It accepts an image
|
|
file as an option, then displays this image in a window. Control-C will quit
|
|
the program. You can resize the window and the image will be resized with
|
|
it. There are two versions - one for Xlib + Imlib, the other for GDK + GDK
|
|
Imlib.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#cccccc><font face=helvetica size=3>
|
|
<b>This program is written for Xlib.</b><br>
|
|
To compile:<br>
|
|
cc test.c -o test -I/usr/X11R6/include -I/usr/local/include -L/usr/X11R6/lib
|
|
-L/usr/local/lib -lX11 -lXext -ljpeg -lpng -ltiff -lz -lgif -lm -lImlib
|
|
</font></td></tr><tr><td bgcolor=#ffffff>
|
|
<pre>
|
|
#include <X11/Xlib.h>
|
|
#include <X11/Xutil.h>
|
|
#include <X11/extensions/shape.h>
|
|
#include <Imlib.h>
|
|
|
|
int main(int argc, char **argv)
|
|
{
|
|
Display *disp;
|
|
ImlibData *id;
|
|
XSetWindowAttributes attr;
|
|
Window win;
|
|
ImlibImage *im;
|
|
Pixmap p,m;
|
|
int w,h;
|
|
|
|
/* Be nice and tell the user if they don't, to provide a file as an arg */
|
|
if (argc<=1)
|
|
{
|
|
printf("Usage:\n %s image_file\n",argv[0]);
|
|
exit(1);
|
|
}
|
|
/* Connect to the default Xserver */
|
|
disp=XOpenDisplay(NULL);
|
|
/* Immediately afterwards Intitialise Imlib */
|
|
id=Imlib_init(disp);
|
|
|
|
/* Load the image specified as the first argument */
|
|
im=Imlib_load_image(id,argv[1]);
|
|
/* Suck the image's original width and height out of the Image structure */
|
|
w=im->rgb_width;h=im->rgb_height;
|
|
/* Create a Window to display in */
|
|
win=XCreateWindow(disp,DefaultRootWindow(disp),0,0,w,h,0,id->x.depth,
|
|
InputOutput,id->x.visual,0,&attr);
|
|
XSelectInput(disp,win,StructureNotifyMask);
|
|
/* Render the original 24-bit Image data into a pixmap of size w * h */
|
|
Imlib_render(id,im,w,h);
|
|
/* Extract the Image and mask pixmaps from the Image */
|
|
p=Imlib_move_image(id,im);
|
|
/* The mask will be 0 if the image has no transparency */
|
|
m=Imlib_move_mask(id,im);
|
|
/* Put the Image pixmap in the background of the window */
|
|
XSetWindowBackgroundPixmap(disp,win,p);
|
|
/* If there was a mask to the image, set the Image's mask to it */
|
|
if (m) XShapeCombineMask(disp,win,ShapeBounding,0,0,m,ShapeSet);
|
|
/* Actually display the window */
|
|
XMapWindow(disp,win);
|
|
/* Synchronise with the Xserver */
|
|
XSync(disp,False);
|
|
/* Event loop to handle resizes */
|
|
for(;;)
|
|
{
|
|
XEvent ev;
|
|
|
|
/* Sit and wait for an event to happen */
|
|
XNextEvent(disp,&ev);
|
|
if (ev.type==ConfigureNotify)
|
|
{
|
|
w=ev.xconfigure.width;h=ev.xconfigure.height;
|
|
/* Re-render the Image to the new size */
|
|
Imlib_render(id,im,w,h);
|
|
/* Free the previous pixmap used for the window - note ONLY the pixmap is */
|
|
/* freed - the mask is marked automatically to be freed along with the */
|
|
/* pixmap. There is no need to free it as well - in fact it is advised you do */
|
|
/* not. You must use the Imlib free function because of Imlib's caching. Do */
|
|
/* not use any other free functions. You can use this function for Pixmaps */
|
|
/* not created by Imlib - and it will just go free them as expected. */
|
|
Imlib_free_pixmap(id,p);
|
|
p=Imlib_move_image(id,im);
|
|
/* The mask will be 0 if the image has no transparency */
|
|
m=Imlib_move_mask(id,im);
|
|
/* Put the Image pixmap in the background of the window */
|
|
XSetWindowBackgroundPixmap(disp,win,p);
|
|
/* If there was a mask to the image, set the Image's mask to it */
|
|
if (m) XShapeCombineMask(disp,win,ShapeBounding,0,0,m,ShapeSet);
|
|
/* Clear the window to update the background change */
|
|
XClearWindow(disp,win);
|
|
/* Synchronise with the Xserver */
|
|
XSync(disp,False);
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
</td></tr></table></center>
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#cccccc><font face=helvetica size=3>
|
|
<b>This program is written for GDK.</b><br>
|
|
To compile:<br>
|
|
cc test.c -o test -I/usr/X11R6/include -I/usr/local/include -L/usr/X11R6/lib
|
|
-L/usr/local/lib -lX11 -lXext -ljpeg -lpng -ltiff -lz -lgif -lglib -lgdk -lm
|
|
-lgdk_imlib
|
|
</font></td></tr><tr><td bgcolor=#ffffff>
|
|
<pre>
|
|
#include <gdk_imlib.h>
|
|
#include <gdk/gdk.h>
|
|
|
|
int main(int argc, char **argv)
|
|
{
|
|
GdkWindowAttr attr;
|
|
GdkWindow *win;
|
|
GdkPixmap *p,*m;
|
|
GdkImlibImage *im;
|
|
gint w,h;
|
|
|
|
/* Be nice and tell the user if they don't, to provide a file as an arg */
|
|
if (argc<=1)
|
|
{
|
|
printf("Usage:\n %s image_file\n",argv[0]);
|
|
exit(1);
|
|
}
|
|
/* Inititalise GDK */
|
|
gdk_init(&argc,&argv);
|
|
/* Immediately after initialising GDK, Initialise Imlib */
|
|
gdk_imlib_init();
|
|
|
|
/* Get gdk to use imlib's visual and colormap */
|
|
gtk_widget_push_visual(gdk_imlib_get_visual());
|
|
gtk_widget_push_colormap(gdk_imlib_get_colormap());
|
|
|
|
/* Load the image specified as the first argument */
|
|
im=gdk_imlib_load_image(argv[1]);
|
|
/* Suck[B the image's original width and height out of the Image structure */
|
|
w=im->rgb_width;h=im->rgb_height;
|
|
/* Set up attributes for GDK to create a Window */
|
|
attr.window_type=GDK_WINDOW_TOPLEVEL;
|
|
attr.wclass=GDK_INPUT_OUTPUT;
|
|
attr.event_mask=GDK_STRUCTURE_MASK;
|
|
attr.width=w;
|
|
attr.height=h;
|
|
/* Create a Window to display in */
|
|
win=gdk_window_new(NULL,&attr,0);
|
|
|
|
/* Render the original 24-bit Image data into a pixmap of size w * h */
|
|
gdk_imlib_render(im,w,h);
|
|
/* Extract the Image and mask pixmaps from the Image */
|
|
p=gdk_imlib_move_image(im);
|
|
/* The mask will be NULL if the image has no transparency */
|
|
m=gdk_imlib_move_mask(im);
|
|
/* Put the Image pixmap in the background of the window */
|
|
gdk_window_set_back_pixmap(win,p,0);
|
|
/* If there was a mask to the image, set the Image's mask to it */
|
|
if (m) gdk_window_shape_combine_mask(win,m,0,0);
|
|
/* Actually display the window */
|
|
gdk_window_show(win);
|
|
/* Flush the GDK buffer */
|
|
gdk_flush();
|
|
/* Event loop to handle resizes */
|
|
for(;;)
|
|
{
|
|
GdkEvent *ev;
|
|
|
|
/* Sit and wait for an event to happen */
|
|
gdk_events_pending();
|
|
/* Drag the event out of the Event queue */
|
|
ev=gdk_event_get();
|
|
/* If the event is a resize event */
|
|
if ((ev)&&(ev->type==GDK_CONFIGURE))
|
|
{
|
|
w=ev->configure.width;h=ev->configure.height;
|
|
gdk_event_free(ev);
|
|
/* Re-render the Image to the new size */
|
|
gdk_imlib_render(im,w,h);
|
|
/* Free the previous pixmap used for the window - note ONLY the pixmap is */
|
|
/* freed - the mask is marked automatically to be freed along with the */
|
|
/* pixmap. There is no need to free it as well - in fact it is advised you do */
|
|
/* not. You must use the Imlib free function because of Imlib's caching. Do */
|
|
/* not use any other free functions. You can use this function for Pixmaps */
|
|
/* not created by Imlib - and it will just go free them as expected. */
|
|
gdk_imlib_free_pixmap(p);
|
|
/* Extract the pixmap out of the Image */
|
|
p=gdk_imlib_move_image(im);
|
|
/* The mask will be NULL if the image has no transparency */
|
|
m=gdk_imlib_move_mask(im);
|
|
/* Set the new pixmap background */
|
|
gdk_window_set_back_pixmap(win,p,0);
|
|
/* If there was a mask to the image, set the Image's mask to it */
|
|
if (m) gdk_window_shape_combine_mask(win,m,0,0);
|
|
/* Clear the window to update the background change */
|
|
gdk_window_clear(win);
|
|
/* Flush GDK's buffer */
|
|
gdk_flush();
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
</td></tr></table></center>
|
|
<p>
|
|
We could now optimize these programs (which are longer than they need to be
|
|
just as an exercise) to use Imlib a bit more. Note the Differences.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#cccccc><font face=helvetica size=3>
|
|
<b>This program is written for Xlib.</b><br>
|
|
To compile:<br>
|
|
cc test.c -o test -I/usr/X11R6/include -I/usr/local/include -L/usr/X11R6/lib
|
|
-L/usr/local/lib -lX11 -lXext -ljpeg -lpng -ltiff -lz -lgif -lm -lImlib
|
|
</font></td></tr><tr><td bgcolor=#ffffff>
|
|
<pre>
|
|
#include <X11/Xlib.h>
|
|
#include <X11/Xutil.h>
|
|
#include <X11/extensions/shape.h>
|
|
#include <Imlib.h>
|
|
|
|
int main(int argc, char **argv)
|
|
{
|
|
Display *disp;
|
|
ImlibData *id;
|
|
XSetWindowAttributes attr;
|
|
Window win;
|
|
ImlibImage *im;
|
|
Pixmap p,m;
|
|
int w,h;
|
|
|
|
/* Be nice and tell the user if they don't, to provide a file as an arg */
|
|
if (argc<=1)
|
|
{
|
|
printf("Usage:\n %s image_file\n",argv[0]);
|
|
exit(1);
|
|
}
|
|
/* Connect to the default Xserver */
|
|
disp=XOpenDisplay(NULL);
|
|
/* Immediately afterwards Intitialise Imlib */
|
|
id=Imlib_init(disp);
|
|
|
|
/* Load the image specified as the first argument */
|
|
im=Imlib_load_image(id,argv[1]);
|
|
/* Suck the image's original width and height out of the Image structure */
|
|
w=im->rgb_width;h=im->rgb_height;
|
|
/* Create a Window to display in */
|
|
win=XCreateWindow(disp,DefaultRootWindow(disp),0,0,w,h,0,id->x.depth,
|
|
InputOutput,id->x.visual,0,&attr);
|
|
XSelectInput(disp,win,StructureNotifyMask);
|
|
/* Put the Image in the window, at the window's size and apply a shape mask */
|
|
/* if applicable, or remove one if not */
|
|
Imlib_apply_image(id,im,win);
|
|
/* Actually display the window */
|
|
XMapWindow(disp,win);
|
|
/* Synchronise with the Xserver */
|
|
XSync(disp,False);
|
|
/* Event loop to handle resizes */
|
|
for(;;)
|
|
{
|
|
XEvent ev;
|
|
|
|
/* Sit and wait for an event to happen */
|
|
XNextEvent(disp,&ev);
|
|
if (ev.type==ConfigureNotify)
|
|
{
|
|
/* Put the Image in the window, at the window's size and apply a shape mask */
|
|
/* if applicable, or remove one if not */
|
|
Imlib_apply_image(id,im,win);
|
|
/* Synchronise with the Xserver */
|
|
XSync(disp,False);
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
</td></tr></table></center>
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#cccccc><font face=helvetica size=3>
|
|
<b>This program is written for GDK.</b><br>
|
|
To compile:<br>
|
|
cc test.c -o test -I/usr/X11R6/include -I/usr/local/include -L/usr/X11R6/lib
|
|
-L/usr/local/lib -lX11 -lXext -ljpeg -lpng -ltiff -lz -lgif -lglib -lgdk -lm
|
|
-lgdk_imlib
|
|
</font></td></tr><tr><td bgcolor=#ffffff>
|
|
<pre>
|
|
#include <gdk_imlib.h>
|
|
#include <gdk/gdk.h>
|
|
|
|
int main(int argc, char **argv)
|
|
{
|
|
GdkWindowAttr attr;
|
|
GdkWindow *win;
|
|
GdkPixmap *p,*m;
|
|
GdkImlibImage *im;
|
|
gint w,h;
|
|
|
|
/* Be nice and tell the user if they don't, to provide a file as an arg */
|
|
if (argc<=1)
|
|
{
|
|
printf("Usage:\n %s image_file\n",argv[0]);
|
|
exit(1);
|
|
}
|
|
/* Inititalise GDK */
|
|
gdk_init(&argc,&argv);
|
|
/* Immediately after initialising GDK, Initialise Imlib */
|
|
gdk_imlib_init();
|
|
|
|
/* Get gdk to use imlib's visual and colormap */
|
|
gtk_widget_push_visual(gdk_imlib_get_visual());
|
|
gtk_widget_push_colormap(gdk_imlib_get_colormap());
|
|
|
|
/* Load the image specified as the first argument */
|
|
im=gdk_imlib_load_image(argv[1]);
|
|
/* Suck the image's original width and height out of the Image structure */
|
|
w=im->rgb_width;h=im->rgb_height;
|
|
/* Set up attributes for GDK to create a Window */
|
|
attr.window_type=GDK_WINDOW_TOPLEVEL;
|
|
attr.wclass=GDK_INPUT_OUTPUT;
|
|
attr.event_mask=GDK_STRUCTURE_MASK;
|
|
attr.width=w;
|
|
attr.height=h;
|
|
/* Create a Window to display in */
|
|
win=gdk_window_new(NULL,&attr,0);
|
|
|
|
/* Put the Image in the window, at the window's size and apply a shape mask */
|
|
/* if applicable, or remove one if not */
|
|
gdk_imlib_apply_image(im,win);
|
|
/* Actually display the window */
|
|
gdk_window_show(win);
|
|
/* Flush the GDK buffer */
|
|
gdk_flush();
|
|
/* Event loop to handle resizes */
|
|
for(;;)
|
|
{
|
|
GdkEvent *ev;
|
|
|
|
/* Sit and wait for an event to happen */
|
|
gdk_events_pending();
|
|
/* Drag the event out of the Event queue */
|
|
ev=gdk_event_get();
|
|
/* If the event is a resize event */
|
|
if ((ev)&&(ev->type==GDK_CONFIGURE))
|
|
{
|
|
gdk_event_free(ev);
|
|
/* Put the Image in the window, at the window's size and apply a shape mask */
|
|
/* if applicable, or remove one if not */
|
|
gdk_imlib_apply_image(im,win);
|
|
/* Flush GDK's buffer */
|
|
gdk_flush();
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
</td></tr></table></center>
|
|
<blockquote>
|
|
<b>As a note for future code snippets:</b><br>
|
|
All data types beginning with <b>Imlib</b> are Xlib Imlib data types, those
|
|
beginning with <b>Gdk</b> are GDK Imlib data types. All functions beginning
|
|
with <b>Imlib_</b> are Xlib Imlib functions and all functions beginning with
|
|
<b>gdk_</b> are GDK Imlib function calls. All calls perform the same
|
|
functions and accept similar parameters - the differences are GDK and Xlib
|
|
primitives, and the Xlib Imlib has an extra ImlibData parameter at the start
|
|
of each function call. Examples of sibling data types and functions calls
|
|
will be given together. Chose the appropriate one for your situation.
|
|
</blockquote>
|
|
<p>
|
|
You will notice we saved a fair few commands - that I have found my code
|
|
littered with all over the place, by using a function in Imlib that does
|
|
this for you. It shows that you can have full control over your programs, if
|
|
you desire, or let Imlib do it for you.
|
|
<p>
|
|
<b>Imlib's concept of an image</b><br>
|
|
Imlib has a certain concept of what an image is. It is designed to be fast,
|
|
fairly general and powerful. For Imlib an image is:
|
|
<ul>
|
|
<li>
|
|
An image is a large chunk of 24-bit pixel data in RGBRGBRGB format.
|
|
<li>
|
|
There is a second chunk of alpha channel data that matches the RGB chunk
|
|
pixel for pixel, but currently is unused, provided for future expansion.
|
|
<li>
|
|
An image contains an optional RGB value that tags all pixels with that value
|
|
as being transparent. This is specifically designed around X's on or off
|
|
transparency and clip mask operations.
|
|
<li>
|
|
Images have a set of border pixels - if not set, the borders are all set to
|
|
0 pixels. The borders are a special set of pixels that are scaled slightly
|
|
differently from the rest of the image when rendered to a pixmap.
|
|
<li>
|
|
Images have attached map-tables that can either be explicitly set, or are
|
|
generated from the image's Gamma, Brightness and Contrast settings (and the
|
|
same settings per Red, Green and Blue channel). These settings and
|
|
map-tables are inherited upon loading from the system settings (currently
|
|
all normalized - will be added to the configuration file and init soon).
|
|
</ul>
|
|
<p>
|
|
The data in the 24-bit representation of an image is a large block of
|
|
unsigned char bytes. The image has a pointer to this data which is in the
|
|
order from top-left pixel to bottom right, scanline by scanline. Each pixel
|
|
is an RGB triplet, with the bytes in the order Red Green Blue, so the array
|
|
looks something like RGBRGBRGBRGBRGBRGB...
|
|
<p>
|
|
If our image is:
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibImage *im;
|
|
GdkImlibImage *im;
|
|
</pre></td></tr></table></center>
|
|
<p>
|
|
The pointer to the RGB data and the alpha data would be:
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
im->rgb_data; /* pointer to unsigned char RGB data */
|
|
im->alpha_data; /* pointer to unsigned char Alpha data */
|
|
</pre></td></tr></table></center>
|
|
<p>
|
|
The alpha data is currently unused and should be ignored - the pointer to it
|
|
should be kept NULL.
|
|
<p>
|
|
The shape color is an RGB value for the pixel color that is to be considered
|
|
transparent. This defines how Imlib renders the image and if it generates a
|
|
mask pixmap on rendering. Certain image formats (GIF, TIFF, PNG, EIM and XPM)
|
|
contain transparency information. This is inherited by Imlib, so
|
|
there is no need to set the shape color. If it is not set, a program can set a
|
|
shape color, or if it is not desired, it can be removed by setting the RGB
|
|
values for the Shape Color to R,G,B -1,-1,-1.
|
|
<p>
|
|
The way to retrieve the shape color, examine it and set it is as follows. It
|
|
is assumes images have been loaded, Imlib initialised etc. already:
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibData *id;
|
|
ImlibImage *im;
|
|
ImlibColor color;
|
|
int r,g,b;
|
|
|
|
Imlib_get_image_shape(id,im,&color);
|
|
r=color.r;
|
|
g=color.g;
|
|
b=color.b;
|
|
color.r=100;
|
|
color.g=50;
|
|
color.b=255;
|
|
Imlib_set_image_shape(id,im,&color);
|
|
|
|
|
|
GdkImlibImage *im;
|
|
GdkImlibColor color;
|
|
int r,g,b;
|
|
|
|
gdk_imlib_get_image_shape(im,&color);
|
|
r=color.r;
|
|
g=color.g;
|
|
b=color.b;
|
|
color.r=100;
|
|
color.g=50;
|
|
color.b=255;
|
|
gdk_imlib_set_image_shape(im,&color);
|
|
</pre></td></tr></table></center>
|
|
<p>
|
|
The Border attribute is where the programmer or user gets to choose border
|
|
scaling attributes. The border values define margins around the image that
|
|
are not to be scaled in that direction (ie the top and bottom borders do not
|
|
get scaled vertically but retain their pixel sizes). The best way to explain
|
|
is with an example.
|
|
<p>
|
|
<center><table border=1>
|
|
<tr>
|
|
<td align=center><img src=border_eg1.gif width=128 alt="Unscaled Image"></td>
|
|
<td><font face= helvetica size=3>
|
|
Notice how this is the original image, with a hilighted bevel of 3 pixels on
|
|
each side. This is the original and so, we want these borders to to remain
|
|
3 pixels wide when the image is scaled to a larger size. The original is
|
|
32x32 pixels.
|
|
</font></td>
|
|
</tr><tr>
|
|
<td align=center><img src=border_eg2.gif width=320 alt="Scaled Image"></td>
|
|
<td><font face= helvetica size=3>
|
|
Here is an example of the image scaled to 80x40 pixels, when the borders are
|
|
set to 0 pixels - notice how the bevels get scaled too, giving quite an
|
|
un-aesthetic look? This is how a vanilla scaling algorithm would work.
|
|
</font></td>
|
|
</tr><tr>
|
|
<td align=center><img src=border_eg3.gif width=320 alt="Scaled Image"></td>
|
|
<td><font face= helvetica size=3>
|
|
Now take a look at this third example scaled to the same size, but it has
|
|
the border attributes set to 3 pixels for top, bottom, left and right
|
|
borders. This time the image looks correct.
|
|
</font></td>
|
|
</tr><tr>
|
|
<td align=center><img src=border_diag.gif alt="Diagram"></td>
|
|
<td><font face= helvetica size=3>
|
|
Note with this diagram that the borders map out an inner and outer boxes with
|
|
corner pieces, effectively dividing the Image into 9 segments. The borders
|
|
need not be of the same width - as shown here, they can each be of a
|
|
different size, allowing for shadows, and other effects that may exist in
|
|
the image.
|
|
</font></td></tr></table></center>
|
|
<p>
|
|
The image map-tables are a set of 3, 256 value lookup tables of unsigned char
|
|
values. These are calculated form the image's brightness, gamma, and
|
|
contrast settings for the image as a whole and each red, green and blue
|
|
channel. You can set and get these values as follows:
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibData *id;
|
|
ImlibImage *im;
|
|
ImlibColorModifier mod;
|
|
double gamma,brightness,contrast;
|
|
|
|
Imlib_get_image_modifier(id,im,&mod);
|
|
gamma=(double)mod.gamma/256;
|
|
brightness=(double)mod.brightness/256;
|
|
contrast=(dobule)mod.contrast/256;
|
|
Imlib_set_image_modifier(id,im,&mod);
|
|
|
|
|
|
GdkImlibImage *im;
|
|
GdkImlibColorModifier mod;
|
|
double gamma,brightness,contrast;
|
|
|
|
gdk_imlib_get_image_modifier(im,&mod);
|
|
gamma=(double)mod.gamma/256;
|
|
brightness=(double)mod.brightness/256;
|
|
contrast=(double)mod.contrast/256;
|
|
gdk_imlib_set_image_modifier(im,&mod);
|
|
</pre></td></tr></table></center>
|
|
<p>
|
|
Note that the contrast, brightness and gamma values are in fact int's. A
|
|
value of 1.0 (unmodified verbatim data) is in fact 256, so to use a value of
|
|
0.5 for any of these, you would have to use a value of 128 etc.
|
|
<p>
|
|
When you set the modifiers, the map-tables (the curves) are re-calculated
|
|
for that image. You have to re-render the image to gain a pixmap with these
|
|
settings in effect.
|
|
<p>
|
|
There are also identical modifier settings for the red, green and blue
|
|
channels, so these can be used for white point adjustment and other functions.
|
|
<p>
|
|
<img src=curve1.gif alt="Curve" align=left>
|
|
It is also possible to gain direct access to these map-table curves and set
|
|
the values in them manually for finer control. There are 3 tables - one for
|
|
red, one for green and one for blue. The functions Imlib_set_image_red_curve,
|
|
Imlib_set_image_green_curve, Imlib_set_image_blue_curve,
|
|
Imlib_get_image_red_curve, Imlib_get_image_green_curve,
|
|
Imlib_get_image_blue_curve, gdk_imlib_set_image_red_curve,
|
|
gdk_imlib_set_image_green_curve, gdk_imlib_set_image_blue_curve,
|
|
gdk_imlib_get_image_red_curve, gdk_imlib_get_image_green_curve, and
|
|
gdk_imlib_get_image_blue_curve will set and get these. You pass the pointer
|
|
to an array of 256 unsigned char's as the last parameter in each of these
|
|
functions to have Imlib fill that table's contents or use that table's
|
|
contents.
|
|
<p>
|
|
By default the map-table is linear if the global gamma, brightness and
|
|
contrast settings are all normal (ie at 256). This would produce a mapping
|
|
table such as the one here on the left. There is a table per channel
|
|
describing this mapping. If you want you could set the table per red, green
|
|
and blue channel to perhaps something like the graph below, that would then
|
|
give a more interesting mapping. The tables for each channel can be different,
|
|
and so could be used for re-coloring images in interesting ways.
|
|
<img src=curve2.gif alt="Curve" align=right>
|
|
<p>
|
|
It is also possible to then use these mappings to in fact modify the original
|
|
24-bit data for the image - making the changes permanent, and thus not
|
|
needing and of the modifiers. To do this you would call the
|
|
Imlib_apply_modifiers_to_rgb or gdk_imlib_apply_modifiers_to_rgb functions.
|
|
<p>
|
|
If you need advanced manipulation of the 24-bit data (eg blurring, other
|
|
convolutions etc.) you may do this to your heart's content. Just remember -
|
|
before you render any pixmaps to call Imlib_changed_image or
|
|
gdk_imlib_changed_image which will prevent Imlib's caching form not updating
|
|
the pixmaps. This marks all pixmaps rendered off that image as being "dirty"
|
|
and so they will never be referenced again by Imlib's caching. Once they are
|
|
all freed and their reference counts are zero, they will be freed from memory.
|
|
<p>
|
|
Below is a list of All Imlib functions - the Xlib version fist, then the GDK
|
|
version listed second. GDK Imlib functions do not use the ImlibData pointer
|
|
at the start, and so this parameter, being common to ALL Xlib Imlib
|
|
functions will not be mentioned, but it will be assumed you realise that it
|
|
is required.
|
|
<hr>
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibData *Imlib_init(Display *disp);
|
|
void gdk_imlib_init();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function inititalised Imlib. It must be called early in the program
|
|
BEFORE any other Imlib functions are called. You must call it AFTER you call
|
|
XOpenDisplay or gdk_init. The Xlib version needs to have the display
|
|
variable passed to it. The Xlib version is capable of running on multiple
|
|
displays - you just init Imlib per display variable.
|
|
<p>
|
|
This function causes Imlib to investigate properties of your XServer - ie,
|
|
is the shared memory extension available? - if so, use it. The depth(s) of
|
|
the visual(s) and choosing the best visual, initializing the caches to be
|
|
empty, load a default palette (if in 8bpp) and set up a dither matrix etc.
|
|
the default palette file is defined in the system or users imrc file as
|
|
PaletteFile which is simply a flat file of line delimited colors, each color
|
|
being space separated hexadecimal values for red, green and blue. See the
|
|
sample palette file provided with Imlib. You can also force Imlib's shared
|
|
memory use off in the system or user's imrc files with the Mit-Shm option
|
|
- shared pixmaps are available if this is turned on, but it is
|
|
currently advised to turn shared pixmaps off due to Xserver design flaws. Some
|
|
operating systems define maximum chunk sizes for shared memory blocks, and so
|
|
Imlib can be told not to create images of greater than a certain size in
|
|
bytes with the Shm_Max_Size option in the imrc file. Image and pixmap caches
|
|
can be turned on or off and set to their sizes here as well.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibData *Imlib_init_with_params(Display *disp, ImlibInitParams *p);
|
|
void gdk_imlib_init_params(GdkImlibInitParams *p);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function inititalised Imlib, BUT allows the programmer to specify
|
|
startup parameters that override the users or system imrc file. Use these
|
|
options with cauthion, as it is assumed you know what you are doing.
|
|
<p>
|
|
The structure containing the parameters to giv Imlib is:
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibInitParams
|
|
{
|
|
int flags;
|
|
int visualid;
|
|
char *palettefile;
|
|
char sharedmem;
|
|
char sharedpixmaps;
|
|
char paletteoverride;
|
|
char remap;
|
|
char fastrender;
|
|
char hiquality;
|
|
char dither;
|
|
int imagecachesize;
|
|
int pixmapcachesize;
|
|
} ImlibInitParams;
|
|
|
|
#define PARAMS_VISUALID 1<<0
|
|
#define PARAMS_PALETTEFILE 1<<1
|
|
#define PARAMS_SHAREDMEM 1<<2
|
|
#define PARAMS_SHAREDPIXMAPS 1<<3
|
|
#define PARAMS_PALETTEOVERRIDE 1<<4
|
|
#define PARAMS_REMAP 1<<5
|
|
#define PARAMS_FASTRENDER 1<<6
|
|
#define PARAMS_HIQUALITY 1<<7
|
|
#define PARAMS_DITHER 1<<8
|
|
#define PARAMS_IMAGECACHESIZE 1<<9
|
|
#define PARAMS_PIXMAPCACHESIZE 1<<10
|
|
</td></tr></table></center>
|
|
<p>
|
|
with a simliar one for gdk (same members), and same defines for the flags.
|
|
<p>
|
|
You set the bits in the flags member with the appropriate defines
|
|
(PARAMS_VISUALID | PARAMS_PALETTEFILE | PARAMS_SHAREDMEM etc.) which flag
|
|
whihc members of the structure are actually relevant and should be used by
|
|
Imlib in overriding the user/system defaults. If the flag bit is set, then
|
|
that structure member is used. the members are as follows:
|
|
<p>
|
|
<b>visualid</b>: contains an int with the visualid to be used by Imlib.<br>
|
|
<br>
|
|
<b>palettefile</b>: string containing the file for the palette file.<br>
|
|
<br>
|
|
<b>sharedmem</b>: is 1 if you want shared memory used, otherwise 0.<br>
|
|
<br>
|
|
<b>sharedpixmaps</b>: is 1 if you want shared pixmaps, otherwise 0.<br>
|
|
<br>
|
|
<b>paletteoverride</b>: 1 if palette remapping is to be forced on, otherwise 0.<br>
|
|
<br>
|
|
<b>remap</b>: 1 for fast remapping 0 for slower more accurate remapping.<br>
|
|
<br>
|
|
<b>fastrender</b>: 1 for fast rendering, 0 for slightly slower rendering.<br>
|
|
<br>
|
|
<b>hiquality</b>: 1 to turn dithering on in 15/16bpp, 0 otherwise.<br>
|
|
<br>
|
|
<b>dither</b>: 1 to turn dithering on in 8bpp or less, otherwise 0.<br>
|
|
<br>
|
|
<b>imagecachesize</b>: the size of the image cache to be used in bytes.<br>
|
|
<br>
|
|
<b>pixmapcachesize</b>: the size of the pixmap cache to be used in bits.<br>
|
|
<br>
|
|
<p>
|
|
Remember the member is ignored if the flags does not contain the bit set for
|
|
that member - if the bit is set, then that member is used.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_get_render_type(ImlibData *id);
|
|
gint gdk_imlib_get_render_type();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns Imlib's current rendering mode. It will return one of:
|
|
<ul>
|
|
RT_PLAIN_PALETTE<br>
|
|
RT_PLAIN_PALETTE_FAST<br>
|
|
RT_DITHER_PALETTE<br>
|
|
RT_DITHER_PALETTE_FAST<br>
|
|
RT_PLAIN_TRUECOL<br>
|
|
RT_DITHER_TRUECOL<br>
|
|
</ul>
|
|
These modes determine how images will appear when rendered as pixmaps. The
|
|
first 4 modes are for 8-bit displays only (though they can be used for
|
|
higher bit displays after the loading of a palette - Imlib won't load a
|
|
palette in higher display depths to save time). If you wish to use these lower
|
|
modes in higher bit depths, you will need to call Imlib_load_colors or
|
|
gdk_imlib_load_colors on a palette file. You can replace the default palette
|
|
any time by first calling Imlib_free_colors or gdk_imlib_free_colors. The
|
|
first 2 modes do not dither the images, and thus are faster. The fast
|
|
versions used a quick 32x32x32 colorcube lookup to obtain a best color match -
|
|
the other versions use a slightly more accurate color matching function, but
|
|
are slower. Dithering gives much better results, but is slower. Dithering
|
|
and Fast remapping are turned on or of in the users or system imrc file. See
|
|
this file and its comments for details. You can ALSO override Imlib using
|
|
truecolor renderers, and force it to use paletted dithered images in higher
|
|
bit depths by turning these render types on, or turning PaletteOverride on in
|
|
the system or user's imrc file.
|
|
<p>
|
|
RT_PLAIN_TRUECOL is used for all higher bit depths (Imlib won't allow this
|
|
mode to be set if the depth is less than or equal to 8 bit). This s a fast
|
|
renderer that provides high quality. RT_DITHER_TRUECOL is an even higher
|
|
quality renderer that only has effect in 15 and 16 bit depths. It dithers in
|
|
these modes to provide the highest quality images. This option is turned on
|
|
by the HighQuality option in the user's or system imrc file.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_render_type(ImlibData *id, int rend_type);
|
|
void gdk_imlib_set_render_type(gint rend_type);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the render type to rend_type which should be one of the
|
|
above listed render types. This is optional and Imlib will default to
|
|
settings provided by the user, system and Xserver. This is primarily here, in
|
|
conjunction with Imlib_get_render_type or gdk_imlib_get_render_type to allow
|
|
fine tweaking by applications of Imlib's rendering performance.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_load_colors(ImlibData *id, char *file);
|
|
gint gdk_imlib_load_colors(char *file);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function loads the named palette file (described in Imlib_init). It is
|
|
advised to call Imlib_free_colors or gdk_imlib_free_colors first before
|
|
calling this. There may be strange effects when changing palettes "on the
|
|
fly" in 8-bit color. All pixmaps should be re-rendered to inherit this new
|
|
palette.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibImage *Imlib_load_image(ImlibData *id, char *file);
|
|
GdkImlibImage *gdk_imlib_load_image(char *file);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function loads the named file and returns a pointer to an image
|
|
structure. Imlib will first check to see if the file has magic numbers
|
|
defining it as a file Imlib can natively read - and then attempt to read it.
|
|
If Imlib doesn't recognise the magic numbers, or certain native loaders
|
|
have not been compiled in, it will fall back to asking Imagemagick's convert
|
|
utility to convert the image into a PPM format image for Imlib to read in.
|
|
If this doesn't work, Imlib will call on the NETPBM utilities to convert the
|
|
image to a PPM for Imlib to read. If this fails, Imlib gives up and returns
|
|
NULL. Imlib does not create any temporary files in this process.
|
|
<p>
|
|
Imlib can, if all native loaders are compiled in, read JPEG, GIF, PPM, PGM,
|
|
XPM, PNG, TIFF and EIM image formats. GIF, PNG, XPM, TIFF and EIM images all
|
|
retain their transparency information when being loaded.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_best_color_match(ImlibData *id, int *r, int *g, int *b);
|
|
gint gdk_imlib_best_color_match(gint *r, gint *g, gint *b);
|
|
</td></tr></table></center>
|
|
<p>
|
|
If the render type is a truecolor one, Imlib returns a pixel value that is
|
|
the closest match to the requested RGB value (RGB each being in the range of
|
|
0-255). This will normally be very close. If using a palette render type,
|
|
Imlib returns the closest match to the allocated palette and the rgb members
|
|
are set to the actual RGB value of the color returned, The function always
|
|
returns the pixel value of this color.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_render(ImlibData *id, ImlibImage *image, int width, int height);
|
|
gint gdk_imlib_render(GdkImlibImage *image, gint width, gint height);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This will render the image pointed to by image into a pixmap of the defined
|
|
width and height. If the image contains transparency, a mask will also be
|
|
rendered. These can be extracted form the image using the functions below.
|
|
If any pixmaps were already existant in the image, these are destroyed upon
|
|
re-rendering the image. If Imlib was unable for some reason to render the
|
|
Image to that pixmap, it will return 0, otherwise it will return 1.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
Pixmap Imlib_copy_image(ImlibData *id, ImlibImage *image);
|
|
GdkPixmap *gdk_imlib_copy_image(GdkImlibImage *image);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This routine returns a copy of the image pixmap. You should use this routine
|
|
if you wish to modify the pixmap itself afterwards by doing any drawing on
|
|
it. Do NOT use the move functions for pixmap that will be modified later.
|
|
You can make multiple copies of the pixmap by calling this function
|
|
repeatedly. If no pixmap was rendered it will return 0 or NULL.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
Pixmap Imlib_copy_mask(ImlibData *id, ImlibImage *image);
|
|
GdkBitmap *gdk_imlib_copy_mask(GdkImlibImage *image);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This is the Imlib_copy_image or gdk_imlib_copy_image functions, but it returns
|
|
the mask for the image. If there is no transparency, or no mask was rendered,
|
|
it returns 0, or NULL.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
Pixmap Imlib_move_image(ImlibData *id, ImlibImage *image);
|
|
GdkPixmap *gdk_imlib_move_image(GdkImlibImage *image);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This returns the rendered pixmap from the image structure, and removes the
|
|
image pixmap (setting it to 0 or NULL) inside the image structure. If you do
|
|
not need to modify the pixmap - ie just use it, this is the function you
|
|
should call. It is faster than Imlib_copy_image or gdk_imlib_copy_image.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
Pixmap Imlib_move_mask(ImlibData *id, ImlibImage *image);
|
|
GdkBitmap *gdk_imlib_move_mask(GdkImlibImage *image);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This is the same as Imlib_move_image or gdk_imlib_move_image but returns the
|
|
mask for the rendered Image.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_destroy_image(ImlibData *id, ImlibImage *image);
|
|
void gdk_imlib_destroy_image(GdkImlibImage *image);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This destroys the Image structure, making it invalid. It reduces the
|
|
reference count on that image and if at zero, it enters the cache. Once the
|
|
cache fills and this image gets to the oldest part of the cache, it will be
|
|
freed when the cache exceeds its boundaries.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_kill_image(ImlibData *id, ImlibImage *image);
|
|
void gdk_imlib_kill_image(GdkImlibImage *image);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This does the same as Imlib_destroy_image or gdk_imlib_destroy_image but
|
|
forces it to be freed immediately once its reference count hits zero - ie it
|
|
does not hang around in the cache.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_free_colors(ImlibData *id);
|
|
void gdk_imlib_free_colors();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This frees the current colormap used by Imlib and all the colors in it,
|
|
setting the color count to zero. It is not a good idea to go rendering
|
|
anything in an 8-bit display if the colors are freed.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_free_pixmap(ImlibData *id, Pixmap pixmap);
|
|
void gdk_imlib_free_pixmap(GdkPixmap *pixmap);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This frees the pixmap pointed to - reducing its reference count by 1. If the
|
|
count is zero it enters the cache and once the cache is filled and the
|
|
pixmap is too old, it is freed. You must use this function for ALL pixmaps
|
|
generated by Imlib. You may use it on Pixmaps not generated by Imlib and it
|
|
will free them as normal. This function ALSO frees (or reduces the reference
|
|
count) on the associated mask pixmap for that image pixmap, if there is a
|
|
mask, so you do not need to free the mask separately.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_border(ImlibData *id, ImlibImage *image, ImlibBorder *border);
|
|
void gdk_imlib_get_image_border(GdkImlibImage *image, GdkImlibBorder *border);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the image's border attributes in the border structure.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_border(ImlibData *id, ImlibImage *image, ImlibBorder *border);
|
|
void gdk_imlib_set_image_border(GdkImlibImage *image, GdkImlibBorder *border);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the image's border attributes to those in the border
|
|
structure.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_shape(ImlibData *id, ImlibImage *image, ImlibColor *color);
|
|
void gdk_imlib_get_image_shape(GdkImlibImage *image, GdkImlibColor *color);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the color of the transparent color in an image - if
|
|
there is no transparent color the RGB members are all set to -1, otherwise
|
|
they are set to the RGB value of this color.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_shape(ImlibData *id, ImlibImage *image, ImlibColor *color);
|
|
void gdk_imlib_set_image_shape(GdkImlibImage *image, GdkImlibColor *color);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the transparent color to the RGB values in the color
|
|
structure. If any of these are -1, transparency for that image is turned off.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_save_image_to_eim(ImlibData *id, ImlibImage *image, char *file);
|
|
gint gdk_imlib_save_image_to_eim(GdkImlibImage *image, char *file);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This Function saves the image into an EIM format image. EIM image format is
|
|
currently under construction. Please come back later.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_add_image_to_eim(ImlibData *id, ImlibImage *image, char *file);
|
|
gint gdk_imlib_add_image_to_eim(GdkImlibImage *image, char *file);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This Function adds the image into an EIM file that currently exists. EIM
|
|
image format is currently under construction. Please come back later.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_save_image_to_ppm(ImlibData *id, ImlibImage *image, char *file);
|
|
gint gdk_imlib_save_image_to_ppm(GdkImlibImage *image, char *file);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function saves the current image as a binary format PPM file. If it is
|
|
successful, it returns 1, otherwise it returns 0.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_load_file_to_pixmap(ImlibData *id, char *filename, Pixmap *pmap, Pixmap *mask);
|
|
gint gdk_imlib_load_file_to_pixmap(char *filename, GdkPixmap **pmap, GdkBitmap **mask);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This is a macro function that does the following. It loads the named image
|
|
file, and sets the pmap and mask variables to the image pixmap and mask
|
|
pixmaps that are rendered at the image's original size. It returns 1 if
|
|
successful and 0 if the load and render do not succeed. It frees the image
|
|
after loading. The pixmaps should be freed by Imlib_free_pixmap or
|
|
gdk_imlib_free_pixmap. This is a nigh identical replacement for
|
|
XpmReadFileToPixmap or gdk_pixmap_create_from_xpm.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_set_image_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the image's brightness, contrast and gamma settings to
|
|
those defined in the mod structure. You need to re-render the image to make
|
|
this have any effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_red_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_set_image_red_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the image's red channel brightness, contrast and gamma
|
|
settings to those defined in the mod structure. You need to re-render the
|
|
image to make this have any effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_green_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_set_image_green_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the image's green channel brightness, contrast and gamma
|
|
settings to those defined in the mod structure. You need to re-render the
|
|
image to make this have any effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_blue_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_set_image_blue_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the image's blue channel brightness, contrast and gamma
|
|
settings to those defined in the mod structure. You need to re-render the
|
|
image to make this have any effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_get_image_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the image's current modifier settings in the mod
|
|
structure.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_red_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_get_image_red_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the image's red channel modifier settings in the mod
|
|
structure.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_green_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_get_image_green_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the image's green channel modifier settings in the mod
|
|
structure.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_blue_modifier(ImlibData *id, ImlibImage *im, ImlibColorModifier *mod);
|
|
void gdk_imlib_get_image_blue_modifier(GdkImlibImage *im, GdkImlibColorModifier *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the image's blue channel modifier settings in the mod
|
|
structure.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_red_curve(ImlibData *id, ImlibImage *im, unsigned char *mod);
|
|
void gdk_imlib_set_image_red_curve(GdkImlibImage *im, unsigned char *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the mapping table curve for the red channel to the
|
|
contents of the array pointer to by mod, which is a 256 element array of
|
|
unsigned char values that map newvalue=mod[value]. This overrides the
|
|
current modifier table generated by any gamma, brightness or contrast
|
|
settings.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_green_curve(ImlibData *id, ImlibImage *im, unsigned char *mod);
|
|
void gdk_imlib_set_image_green_curve(GdkImlibImage *im, unsigned char *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the mapping table curve for the green channel to the
|
|
contents of the array pointer to by mod, which is a 256 element array of
|
|
unsigned char values that map newvalue=mod[value]. This overrides the
|
|
current modifier table generated by any gamma, brightness or contrast
|
|
settings.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_image_blue_curve(ImlibData *id, ImlibImage *im, unsigned char *mod);
|
|
void gdk_imlib_set_image_blue_curve(GdkImlibImage *im, unsigned char *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the mapping table curve for the blue channel to the
|
|
contents of the array pointer to by mod, which is a 256 element array of
|
|
unsigned char values that map newvalue=mod[value]. This overrides the
|
|
current modifier table generated by any gamma, brightness or contrast
|
|
settings.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_red_curve(ImlibData *id, ImlibImage *im, unsigned char *mod);
|
|
void gdk_imlib_set_image_red_curve(GdkImlibImage *im, unsigned char *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the current red channel mapping table curve by copying
|
|
its contents into the 256 element array of unsigned char's pointed to by mod.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_green_curve(ImlibData *id, ImlibImage *im, unsigned char *mod);
|
|
void gdk_imlib_get_image_green_curve(GdkImlibImage *im, unsigned char *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the current green channel mapping table curve by copying
|
|
its contents into the 256 element array of unsigned char's pointed to by mod.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_get_image_blue_curve(ImlibData *id, ImlibImage *im, unsigned char *mod);
|
|
void gdk_imlib_get_image_blue_curve(GdkImlibImage *im, unsigned char *mod);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the current blue channel mapping table curve by copying
|
|
its contents into the 256 element array of unsigned char's pointed to by mod.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_apply_modifiers_to_rgb(ImlibData *id, ImlibImage *im);
|
|
void gdk_imlib_apply_modifiers_to_rgb(GdkImlibImage *im);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function takes all the current RGB mapping tables and modifies the
|
|
original 24-bit RGB data to match. This dirties all cached pixmaps of that
|
|
image, and you will need to re-render the image for it to take any effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_changed_image(ImlibData *id, ImlibImage *im);
|
|
void gdk_imlib_changed_image(GdkImlibImage *im);
|
|
</td></tr></table></center>
|
|
<p>
|
|
If you go and modify the image's RGB data yourself via your own routines,
|
|
once finished and before rendering any more pixmaps, you should call this
|
|
function to inform Imlib that the contents of the image have changed.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_apply_image(ImlibData *id, ImlibImage *im, Window p);
|
|
void gdk_imlib_apply_image(GdkImlibImage *im, GdkWindow *p);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function takes an image, renders it at the size of the window specified
|
|
as p, sets the window's background pixmap to be this rendered pixmap, and
|
|
sets the window's shape mask to the the mask for the image if it has any
|
|
transparency. It frees both pixmaps after use.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_paste_image(ImlibData *id, ImlibImage *im, Window p, int x, int y, int w, int h);
|
|
void gdk_imlib_paste_image(GdkImlibImage *im, GdkWindow *p, gint x, gint y, gint w, gint h);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This pastes a pixmap of the image at the x,y co-ordinates in the drawable p
|
|
(which can be either a window or a pixmap), and uses the shape mask to
|
|
determine which pixels are actually drawn. It is effectively like pasting
|
|
the image at that size at that location. Both the pixmap and the mask are
|
|
freed afterwards.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_paste_image_border(ImlibData *id, ImlibImage *im, Window p, int x, int y, int w, int h);
|
|
void gdk_imlib_paste_image_border(GdkImlibImage *im, GdkWindow *p, gint x, gint y, gint w, gint h);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function works just like Imlib_paste_image or gdk_imlib_paste_image,
|
|
but only pastes the borders of the image. This is handy if the image is
|
|
being used to define bevel borders on a button for maximum efficiency.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_flip_image_horizontal(ImlibData *id, ImlibImage *im);
|
|
void gdk_imlib_flip_image_horizontal(GdkImlibImage *im);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This flips the RGB data in an image horizontally. You need to re-render the
|
|
image for it to take effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_flip_image_vertical(ImlibData *id, ImlibImage *im);
|
|
void gdk_imlib_flip_image_vertical(GdkImlibImage *im);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This flips the RGB data in an image vertically. You need to re-render the
|
|
image for it to take effect.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_rotate_image(ImlibData *id, ImlibImage *im, int d);
|
|
void gdk_imlib_rotate_image(GdkImlibImage *im, gint d);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function currently is a bit of a misnomer. It does not use the d
|
|
parameter - it merely mirrors the image about a diagonal line going from the
|
|
top-left to the bottom right at 45 degrees. It effectively rotates the image,
|
|
combined with flips horizontally and vertically this can be used to give the
|
|
image any orientation in steps of 90 degrees. This function needs some work
|
|
(it must use the d parameter to work out which way to rotate and how much - 1
|
|
rotates clockwise, -1 counter-clockwise by 90 degrees, 2 or -2 180 degrees etc.)
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibImage *Imlib_create_image_from_data(ImlibData *id, unsigned char *data, unsigned char *alpha, int w, int h);
|
|
GdkImlibImage *gdk_imlib_create_image_from_data(unsigned char *data, unsigned char *alpha, gint w, gint h);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function take a pointer to 24-bit RGB data (in the format RGBRGBRGB)
|
|
and creates an image of size w x h out of it that can then be used by
|
|
Imlib's routines for rendering. The pointer to the alpha data is currently
|
|
unused and is there for future use. If successful it returns a pointer to
|
|
the image, or NULL of unsuccessful. The data pointed to is copied into the
|
|
image. This means you may free or destroy this original data or do with it
|
|
as you see fit without affecting Imlib's image.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibImage *Imlib_clone_image(ImlibData *id, ImlibImage *im);
|
|
GdkImlibImage *gdk_imlib_clone_image(GdkImlibImage *im);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function makes a duplicate copy of the image pointed to. If
|
|
unsuccessful it returns NULL, otherwise it returns a pointer to the new image.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibImage *Imlib_clone_scaled_image(ImlibData *id, ImlibImage *im, int w, int h);
|
|
GdkImlibImage *gdk_imlib_clone_scaled_image(GdkImlibImage *im, int w, int h);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This Function creates a duplicate image scaled to the size w x h of the
|
|
image pointed to - the 24-bit data is what is scaled. If successful it
|
|
returns a pointer to the new image or NULL if not.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
int Imlib_get_fallback(ImlibData *id);
|
|
gint gdk_imlib_get_fallback();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function gets the status of ImageMagick and NETPBM fallback mechanisms.
|
|
1 means they are active, 0 means they are not.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void Imlib_set_fallback(ImlibData *id, int fallback);
|
|
void gdk_imlib_set_fallback(gint fallback);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function sets the state of the ImageMagick and NETPBM fallback
|
|
mechanisms. 1 makes them active, 0 deactivates them.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
Visual *Imlib_get_visual(ImlibData *id);
|
|
GdkVisual *gdk_imlib_get_visual();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the Visual that Imlib has decided to use (accoridng to
|
|
imrc and XServer capabilities).
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
Colormap Imlib_get_colormap(ImlibData *id);
|
|
GdkColormap *gdk_imlib_get_colormap();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns the Colormap that Imlib has chosen to use for its
|
|
visual.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
char *Imlib_get_sysconfig(ImlibData *id);
|
|
gchar *gdk_imlib_get_sysconfig();
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function returns a pointer to a copy of the path to the system imrc
|
|
file. When finished you should free this string.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
ImlibImage *Imlib_create_image_from_xpm_data(ImlibData *id, char **data);
|
|
GdkImlibImage *gdk_imlib_create_image_from_xpm_data(char **data);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function creates an Imlib image out of an inlined XPM image
|
|
(ie. #include "file.xpm"). data is the pointer to the XPM data.
|
|
<p>
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
gint gdk_imlib_data_to_pixmap(char **data, GdkPixmap **pmap, GdkBitmap **mask);
|
|
int Imlib_data_to_pixmap(ImlibData *id, char **data, Pixmap *pmap, Pixmap *mask);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function creates a pixmap (and optionally a mask) out of the data
|
|
pointed to by data. This data is in the form of an XPM file that has been
|
|
included into the source (eg #include "file.xpm"). If the XPM data has no
|
|
transparency the mask is set to 0 or NULL. The pmap is set to the pixmap
|
|
created. If the operation fails 0 is returned, otherwise 1 is returned.
|
|
<p>
|
|
<hr>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void gdk_imlib_crop_image(GdkImlibImage *im, gint x, gint y, gint w, gint h);
|
|
void Imlib_crop_image(ImlibData *id, ImlibImage *im, int x, int y, int w, int h);
|
|
</td></tr></table></center>
|
|
<p>
|
|
When called, this function will crop out the section of the 24-bit original
|
|
image specified by the rectangle with its top-left corner at (x,y) and with
|
|
width w and height h in pixels. These pixels are pixels in the original
|
|
24-bit data held in the image structure, not a scaled down or up rendered
|
|
version.
|
|
<p>
|
|
<hr>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
GdkImlibImage *gdk_imlib_crop_and_clone_image(GdkImlibImage *im, gint x, gint y, gint w, gint h);
|
|
ImlibImage *Imlib_crop_and_clone_image(ImlibData *id, ImlibImage *im, int x, int y, int w, int h);
|
|
</td></tr></table></center>
|
|
<p>
|
|
When called, this function will crop out the section of the 24-bit original
|
|
image specified by the rectangle with its top-left corner at (x,y) and with
|
|
width w and height h in pixels. These pixels are pixels in the original
|
|
24-bit data held in the image structure, not a scaled down or up rendered
|
|
version. Instead of modifying the original, it makes a copy of the Image and
|
|
returns that. NULL is returned if the crop fails.
|
|
<p>
|
|
<hr>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
void gdk_imlib_best_color_get(GdkColor *c);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This is a gdk_imlib only API call, as much of GTK and GDK pass GdkColor
|
|
structs around, and so Imlbi will fill the pixel value of the GdkColro and
|
|
set the red, green and blue members to a member form Imlib's palette (unless
|
|
it is in 15bpp or higher and palette remapping sin't forced), thus
|
|
conserving colors wherever possible. In truecolor and higher it will give
|
|
exact matches.
|
|
<p>
|
|
<hr>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
gint gdk_imlib_save_image(GdkImlibImage *im, char *file, GdkImlibSaveInfo *info);
|
|
int Imlib_save_image(ImlibData *id, ImlibImage *im, char *file, ImlibSaveInfo *info);
|
|
</td></tr></table></center>
|
|
<p>
|
|
This function is for those who want brain-dead saving in a single function.
|
|
It will save the image pointed to as the file passed. The extension is used
|
|
to determine filetype to save as, so saving as image.jpg will save as a jpeg,
|
|
or saving as file.png will save as a png file etc. The info pointer can be
|
|
NULL, in which case the image will be saved with certain settings if the
|
|
format supports it. for example a jpeg image will always be saved at 80%
|
|
quality unless you provide a pointer to this structre and set the quality
|
|
member to a value from 0 to 256, 256 being 100% quality, 0 being 0% quality.
|
|
Only jpeg images use this member. The other members of the info structure are
|
|
used for postscript saving, so if you plan to output as a postscript, file
|
|
set the members in the structure. The scaling member is a value, with 1024
|
|
meaning "scale the image to maximum size on paper", 512 meaning "half the paper
|
|
size" and 0 meaning zero size. you can use larger values, but the image will
|
|
be clipped to the border of your paper. The color member is either 0 or 1 -
|
|
1 meaning save as color, 0 meaning save as grayscale. the x and
|
|
yjustification members specify a justification in the x and y directions (on
|
|
paper relative to the bottom-left of the page) - 1024 meaning right or top
|
|
justify, 0 meaning left or bottom justify. Using values inbetween (like
|
|
512,512) will give center justification or many variations inbetween.
|
|
<p>
|
|
The page_size member can be one of PAGE_SIZE_EXECUTIVE, PAGE_SIZE_LETTER,
|
|
PAGE_SIZE_LEGAL, PAGE_SIZE_A4, PAGE_SIZE_A3, PAGE_SIZE_A5, or
|
|
PAGE_SIZE_FOLIO. This specifies the page size for the postscript output.
|
|
<p>
|
|
<hr>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
GdkImlibImage *gdk_imlib_create_image_from_drawable(GdkWindow *gwin, GdkBitmap *gmask, int x, int y, int width, int height);
|
|
ImlibImage *Imlib_create_image_from_drawable(ImlibData *id, Drawable win, Pixmap mask, int x, int y, int width, int height);
|
|
</td></tr></table></center>
|
|
<p>
|
|
These functions create an Imlib Image out of an X drawable. The Drawable
|
|
(win or gwin) is either a pixmap or a window. The mask is a mask pixmap
|
|
(optional for creating the mask for the image - currently unused - reserved
|
|
for future use). X, y, width and height describe a rectangle inside the
|
|
drawable (x, and y being relative to the drawable's top-left corner). This
|
|
function, if successful will return a pointer to an image (NOTE to advanced
|
|
programmers - this function internally performs server grabs - it means if
|
|
you had a grab before this function you will no longer have it afterwards.
|
|
This is necessary to avoid race conditions that could kill your client).
|
|
<p>
|
|
<hr>
|
|
<p>
|
|
Here are some data types that you may be interested in (note I have only
|
|
listed the structure members that you should view or play with. It is not
|
|
advisable to play with any structure members, but inspecting them is fine).
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibBorder
|
|
{
|
|
int left,right;
|
|
int top,bottom;
|
|
} ImlibBorder;
|
|
|
|
typedef struct _GdkImlibBorder
|
|
{
|
|
gint left,right;
|
|
gint top,bottom;
|
|
} GdkImlibBorder;
|
|
</td></tr></table></center>
|
|
<p>
|
|
This is the structure containing the border pixel settings in pixels from
|
|
their respective sides. Normally all images have borders of 0,0,0,0.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibColor
|
|
{
|
|
int r,g,b;
|
|
} ImlibColor;
|
|
|
|
typedef struct _GdkImlibColor
|
|
{
|
|
gint r,g,b;
|
|
} GdkImlibColor;
|
|
</td></tr></table></center>
|
|
<p>
|
|
The r,g and b members are ints in the range 0 - 255. If any value is -1, and
|
|
this is used to set or get that shape color, the shape color is either off,
|
|
or will be turned off.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibColorModifier
|
|
{
|
|
int gamma;
|
|
int brightness;
|
|
int contrast;
|
|
} ImlibColorModifier;
|
|
|
|
typedef struct _GdkImlibColorModifier
|
|
{
|
|
gint gamma;
|
|
gint brightness;
|
|
gint contrast;
|
|
} GdkImlibColorModifier;
|
|
</td></tr></table></center>
|
|
<p>
|
|
The members of this structure are fairly self-evident. They are integers,
|
|
with 256 being taken as a value of 1.0. Multiply your gamma, brightness and
|
|
contrast values by 256 to get a value to put in these structures.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibImage
|
|
{
|
|
int rgb_width,rgb_height;
|
|
unsigned char *rgb_data;
|
|
unsigned char *alpha_data;
|
|
char *filename;
|
|
} ImlibImage;
|
|
|
|
typedef struct _GdkImlibImage
|
|
{
|
|
gint rgb_width,rgb_height;
|
|
unsigned char *rgb_data;
|
|
unsigned char *alpha_data;
|
|
gchar *filename;
|
|
} GdkImlibImage;
|
|
</td></tr></table></center>
|
|
<p>
|
|
These are the image data structures. You may read all these data members,
|
|
and you may edit the data that rgb_data and alpha_data point to. Remember
|
|
that if you modify this data to call Imlib_apply_modifiers_to_rgb or
|
|
gdk_imlib_apply_modifiers_to_rgb to dirty the pixmaps in the cache. You may
|
|
not free this data or change the pointer. Currently the alpha_data member is
|
|
unused and will remain NULL. Setting it to anything else may produce
|
|
unexpected results.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibSaveInfo
|
|
{
|
|
int quality;
|
|
int scaling;
|
|
int xjustification;
|
|
int yjustification;
|
|
int page_size;
|
|
char color;
|
|
} ImlibSaveInfo;
|
|
|
|
typedef struct _GdkImlibSaveInfo
|
|
{
|
|
int quality;
|
|
int scaling;
|
|
int xjustification;
|
|
int yjustification;
|
|
int page_size;
|
|
char color;
|
|
} GdkImlibSaveInfo;
|
|
</td></tr></table></center>
|
|
<p>
|
|
These are the ImlibSaveInfo data structs - they may be expanded in future.
|
|
Their use is described above in the imlib_save_image function.
|
|
<p>
|
|
<center><table width=100% border=1><tr><td bgcolor=#ffffff><pre>
|
|
typedef struct _ImlibData
|
|
{
|
|
struct _xdata
|
|
{
|
|
Display *disp;
|
|
int screen;
|
|
Window root;
|
|
Visual *visual;
|
|
int depth;
|
|
} x;
|
|
} ImlibData;
|
|
</td></tr></table></center>
|
|
<p>
|
|
This data structure is not visible in the GDK version of Imlib. It is
|
|
expected for the Xlib version, that all applications that will place pixmaps
|
|
in their windows, create those windows with the depth and visual in Imlib's
|
|
ImlibData - Imlib hunts and chooses the best quality visual on the Xserver
|
|
for its rendering. If you do not use this visual and depth the results are
|
|
implementation dependent - ie, may vary between Xservers.
|
|
</font>
|
|
</body>
|
|
</html>
|