summaryrefslogtreecommitdiffstats
path: root/kimgio/README
blob: 6c9cec844217b8bde76d28e18830b781b05f794d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
KDE Image I/O library
---------------------
This library allows applications that use the Qt library
(i.e. QImageIO, QImage, QPixmap and friends) to read and
write images in extra formats. Current formats include:

JPEG	<read> <write>
JPEG2000 <read> <write>
XV	<read> <write>
EPS	<read> <write>
NETPBM	<incomplete>
PNG	<read> <write, only with newer libraries>
TIFF	<read>
TGA	<read> <write>
PCX	<read> <write>
SGI	<read> <write>   (images/x-rgb: *.bw, *.rgb, *.rgba, *.sgi)
DDS	<read>
XCF	<read>

(Some example files are in kdenonbeta/kimgio_examples.)


To use these formats, you only need to:

1. link the application with the libkio library
2. Include the <kimageio.h> header
3. call KImageIO::registerFormats() once, somewhere in your code
   before you load an image.

Writing handlers
----------------

0. Please read the documentation for the QImageIO class in the Qt
documentation.

1. When writing handlers, there is a function naming convention;
suppose, for example, we were writing PNG read and write handlers,
we would name them

void kimgio_png_read ( QImageIO * );
void kimgio_png_write( QImageIO * );

ie

kimgio_<format>_<read/write>

This should reduce the chance of identifier clashes with other code.

2. Remember that a given KDE application may try to load dozens of
images at once such as when loading icons, or creating thumbnails.
Also, it may well be loading them over a network connection.
Therefore,

	- Avoid creating temporary files or allocating too much memory
	when decoding and encoding. Especially try to avoid firing off
	external programs.

	- Don't assume that the IODevice which is the source or target
	of the image data is pointing to a file on the local filesystem.
	Use the IODevice methods to read and write image data.

	- Check for file corruption or premature end of the image,
	especially before using values read from the file
	e.g. for memory allocations.

3. If you only have either a reader or the writer for a particular
format, don't use NULL in QImageIO::defineIOHandler. Instead, write
a stub function for the unimplemented handler which displays a message
on standard output. This prevents kimgio-using programs dumping core
when attempting to call the unimplemented handler.


Yours in good faith and pedantry,

Sirtaj Singh Kang <taj@kde.org>, 23 September 1998.