From ce4a32fe52ef09d8f5ff1dd22c001110902b60a2 Mon Sep 17 00:00:00 2001
From: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>
Date: Wed, 25 Nov 2009 17:56:58 +0000
Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
 BUG:215923

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
---
 kimgio/README | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 kimgio/README

(limited to 'kimgio/README')

diff --git a/kimgio/README b/kimgio/README
new file mode 100644
index 000000000..6c9cec844
--- /dev/null
+++ b/kimgio/README
@@ -0,0 +1,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.
-- 
cgit v1.2.1