path: root/sip/qt/qimage.sip

// This is the SIP interface definition for QImage, QImageIO and
// QImageTextKeyLang.
//
// Copyright (c) 2007
// 	Riverbank Computing Limited <info@riverbankcomputing.co.uk>
// 
// This file is part of PyQt.
// 
// This copy of PyQt is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation; either version 2, or (at your option) any later
// version.
// 
// PyQt is supplied in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
// details.
// 
// You should have received a copy of the GNU General Public License along with
// PyQt; see the file LICENSE.  If not, write to the Free Software Foundation,
// Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.


%ExportedDoc
<Sect2><Title>QImage</Title>
<Para>
The Python <Literal>==</Literal> and <Literal>!=</Literal> operators are
supported.
</Para>

<FuncSynopsis>
        <FuncDef><Function>QImage</Function></FuncDef>
        <ParamDef>const char *<Parameter>xpm</Parameter>[]</ParamDef>
</FuncSynopsis>
<Para>
This takes a list of strings as its parameter.
</Para>

<FuncSynopsis>
        <FuncDef><Function>QImage</Function></FuncDef>
        <ParamDef>uchar *<Parameter>data</Parameter></ParamDef>
        <ParamDef>int <Parameter>w</Parameter></ParamDef>
        <ParamDef>int <Parameter>h</Parameter></ParamDef>
        <ParamDef>int <Parameter>depth</Parameter></ParamDef>
        <ParamDef>QRgb *<Parameter>colorTable</Parameter></ParamDef>
        <ParamDef>int <Parameter>numColors</Parameter></ParamDef>
        <ParamDef>Endian <Parameter>bitOrder</Parameter></ParamDef>
</FuncSynopsis>
<Para>
The <Literal>colorTable</Literal> parameter is a list of QRgb instances or
None.  (Qt v2.1+)
</Para>

<FuncSynopsis>
        <FuncDef>uchar *<Function>bits</Function></FuncDef>
        <ParamDef></ParamDef>
</FuncSynopsis>
<Para>
The return value is a <Literal>sip.voidptr</Literal> object which is only
useful if passed to another Python module.
</Para>

<FuncSynopsis>
        <FuncDef>QRgb *<Function>colorTable</Function></FuncDef>
        <ParamDef></ParamDef>
</FuncSynopsis>
<Para>
The return value is a <Literal>sip.voidptr</Literal> object which is only
useful if passed to another Python module.
</Para>

<FuncSynopsis>
        <FuncDef>QImage <Function>convertDepthWithPalette</Function></FuncDef>
        <ParamDef>int</ParamDef>
        <ParamDef>QRgb *<Parameter>p</Parameter></ParamDef>
        <ParamDef>int <Parameter>pc</Parameter></ParamDef>
        <ParamDef>int <Parameter>cf</Parameter> = 0</ParamDef>
</FuncSynopsis>
<Para>
Not implemented.
</Para>

<FuncSynopsis>
        <FuncDef>uchar **<Function>jumpTable</Function></FuncDef>
        <ParamDef></ParamDef>
</FuncSynopsis>
<Para>
The return value is a <Literal>sip.voidptr</Literal> object which is only
useful if passed to another Python module.
</Para>

<FuncSynopsis>
	<FuncDef>bool <Function>loadFromData</Function></FuncDef>
	<ParamDef>const uchar *<Parameter>buf</Parameter></ParamDef>
	<ParamDef>uint <Parameter>len</Parameter></ParamDef>
	<ParamDef>const char *<Parameter>format</Parameter> = 0</ParamDef>
	<ParamDef>ColorMode <Parameter>mode</Parameter> = Auto</ParamDef>
</FuncSynopsis>
<Para>
<Literal>len</Literal> is derived from <Literal>buf</Literal> and not passed as
a parameter.
</Para>

<FuncSynopsis>
        <FuncDef>uchar *<Function>scanLine</Function></FuncDef>
        <ParamDef>int <Parameter>i</Parameter></ParamDef>
</FuncSynopsis>
<Para>
The return value is a <Literal>sip.voidptr</Literal> object which is only
useful if passed to another Python module.
</Para>
</Sect2>

<Sect2><Title>QImageIO</Title>
<FuncSynopsis>
	<FuncDef>static void <Function>defineIOHandler</Function></FuncDef>
	<ParamDef>const char *<Parameter>format</Parameter></ParamDef>
	<ParamDef>const char *<Parameter>header</Parameter></ParamDef>
	<ParamDef>const char *<Parameter>flags</Parameter></ParamDef>
	<ParamDef>image_io_handler <Parameter>read_image</Parameter></ParamDef>
	<ParamDef>image_io_handler <Parameter>write_image</Parameter></ParamDef>
</FuncSynopsis>
<Para>
Not implemented.
</Para>
</Sect2>

<Sect2><Title>QImageTextKeyLang</Title>
<Para>
<Literal>QImageTextKeyLang</Literal> is fully implemented.
</Para>
</Sect2>
%End


class QImage
{
%TypeHeaderCode
#include <qimage.h>
%End

public:
	enum Endian {
		IgnoreEndian,
		BigEndian,
		LittleEndian
	};

	QImage();
	QImage(int,int,int,int = 0,Endian = IgnoreEndian);
	QImage(const QSize &,int,int = 0,Endian = IgnoreEndian);
%If (- Qt_2_00)
	QImage(const char *,char * = 0);
%End
%If (Qt_2_00 -)
	QImage(const QString &,char * = 0);
%End

	QImage(SIP_PYLIST) [(const char **)];
%MethodCode
		// The Python interface is a list of strings that make up the
		// image.

		const char **str;

		if ((str = PyQt_qt_ListToArray(a0)) == NULL)
			sipIsErr = 1;
		else
		{
			// There is no wrapper class for QImage.

			Py_BEGIN_ALLOW_THREADS
			sipCpp = new QImage(str);
			Py_END_ALLOW_THREADS

			sipFree((ANY *)str);
		}
%End

%If (Qt_2_00 -)
	QImage(const QByteArray &);
%End

%If (Qt_2_1_0 -)
	QImage(uchar *,int,int,int,SIP_PYLIST /AllowNone/,int,Endian) [(uchar *,int,int,int,int,QRgb *,int,Endian)];
%MethodCode
		// The Python interface takes a list of QRgb instances.

		QRgb *coltab;

		if (a4 == Py_None)
			coltab = 0;
		else
		{
			int len = PyList_Size(a4);

			if (a5 > len)
				a5 = len;

			coltab = new QRgb[len];

			PyErr_Clear();

			for (int i = 0; i < a5; ++i)
			{
				coltab[i] = PyLong_AsUnsignedLong(PyList_GetItem(a4,i));

				if (PyErr_Occurred())
				{
					delete[] coltab;
					sipIsErr = 1;
					break;
				}
			}
		}

		if (!sipIsErr)
		{
			// There is no wrapper class for QImage.

			Py_BEGIN_ALLOW_THREADS
			sipCpp = new QImage(a0,a1,a2,a3,0,a5,(QImage::Endian)a6);

			if (coltab)
			{
				// Now set the colours using the QImage's self
				// allocated colour table.  If we had passed in
				// coltab as the colour table then we couldn't
				// have freed it and it would leak.
				for (int i = 0; i < a5; ++i)
					sipCpp -> setColor(i,coltab[i]);

				delete[] coltab;
			}
			Py_END_ALLOW_THREADS
		}
%End
%End

	QImage(const QImage &);

	bool operator==(const QImage &) const;
	bool operator!=(const QImage &) const;

	void detach();
	QImage copy() const;
	QImage copy(int,int,int,int,int = 0) const;
%If (- Qt_3_0_0)
	QImage copy(QRect &) const;
%End
%If (Qt_3_0_0 -)
	QImage copy(const QRect &) const;
%End
%If (Qt_3_1_0 -)
	static QImage fromMimeSource(const QString &);
%End
	bool isNull() const;

	int width() const;
	int height() const;
	QSize size() const;
	QRect rect() const;
	int depth() const;
	int numColors() const;
	Endian bitOrder() const;

	QRgb color(int) const;
	void setColor(int,QRgb);
	void setNumColors(int);

	bool hasAlphaBuffer() const;
	void setAlphaBuffer(bool);

	bool allGray() const;
	bool isGrayscale() const;

	// Actually returns uchar *.
	void *bits() const;
	// Actually returns uchar *.
	void *scanLine(int) const;
	// Actually returns uchar **.
	void *jumpTable() const;
	// Actually returns QRgb *.
	void *colorTable() const;
	int numBytes() const;
	int bytesPerLine() const;

	bool create(int,int,int,int = 0,Endian = IgnoreEndian);
	bool create(const QSize &,int,int = 0,Endian = IgnoreEndian);
	void reset();

	void fill(uint);
%If (Qt_2_00 -)
	void invertPixels(bool = 1);
%End

	QImage convertDepth(int) const;
//	QImage convertDepthWithPalette(int,QRgb *,int,int = 0) const;
	QImage convertDepth(int,int) const;
	QImage convertBitOrder(Endian) const;

%If (- Qt_3_0_0)
	QImage smoothScale(int,int) const;
%End
%If (Qt_3_0_0 -)
	enum ScaleMode {
		ScaleFree,
		ScaleMin,
		ScaleMax
	};

	QImage smoothScale(int,int,ScaleMode = ScaleFree) const;
	QImage smoothScale(const QSize &,ScaleMode = ScaleFree) const;
	QImage scale(int,int,ScaleMode = ScaleFree) const;
	QImage scale(const QSize &,ScaleMode = ScaleFree) const;
	QImage scaleWidth(int) const;
	QImage scaleHeight(int) const;
	QImage xForm(const QWMatrix &) const;
%End

%If (- Qt_2_00)
	QImage createAlphaMask(bool = 0) const;
	QImage createAlphaMask(int) const;
%End
%If (Qt_2_00 -)
	QImage createAlphaMask(int = 0) const;
%End
	QImage createHeuristicMask(bool = 1) const;
%If (Qt_2_00 -)
	QImage mirror() const;
%End
%If (Qt_2_1_0 -)
	QImage mirror(bool,bool) const;
%End
%If (Qt_2_00 -)
	QImage swapRGB() const;
%End

	static Endian systemBitOrder();
	static Endian systemByteOrder();

%If (- Qt_2_00)
	static const char *imageFormat(const char *);
%End
%If (Qt_2_00 -)
	static const char *imageFormat(const QString &);
%End
	static QStrList inputFormats();
	static QStrList outputFormats();
%If (Qt_2_1_0 -)
	static QStringList inputFormatList();
	static QStringList outputFormatList();
%End
%If (- Qt_2_00)
	bool load(const char *,const char * = 0);
%End
%If (Qt_2_00 -)
	bool load(const QString &,const char * = 0);
%End
	bool loadFromData(const uchar * /Array/,uint /ArraySize/,
			  const char * = 0);
	bool loadFromData(QByteArray,char * = 0);
%If (- Qt_2_00)
	bool save(const char *,const char *) const;
%End
%If (Qt_2_00 - Qt_3_0_0)
	bool save(const QString &,const char *) const;
%End
%If (Qt_2_2_0 - Qt_3_0_0)
	bool save(const QString &,const char *,int) const;
%End
%If (Qt_3_0_0 -)
	bool save(const QString &,const char *,int = -1) const;
%End
%If (Qt_3_2_0 -)
	bool save(QIODevice *,const char *,int = -1) const;
%End

	bool valid(int,int) const;
	int pixelIndex(int,int) const;
	QRgb pixel(int,int) const;
	void setPixel(int,int,uint);

%If (Qt_2_1_0 -)
	int dotsPerMeterX() const;
	int dotsPerMeterY() const;
	void setDotsPerMeterX(int);
	void setDotsPerMeterY(int);
	QPoint offset() const;
	void setOffset(const QPoint &);
%If (Qt_IMAGE_TEXT)
	QValueList<QImageTextKeyLang> textList() const;
	QStringList textLanguages() const;
	QStringList textKeys() const;
	QString text(const char *,const char * = 0) const;
	QString text(const QImageTextKeyLang &) const;
	void setText(const char *,const char *,const QString &);
%End
%End
};


void bitBlt(QImage *,int,int,const QImage *,int = 0,int = 0,int = -1,int = -1,
	    int = 0);


class QImageIO
{
%TypeHeaderCode
#include <qimage.h>
%End

public:
	QImageIO();
	QImageIO(QIODevice *,const char *);
%If (Qt_2_00 -)
	QImageIO(const QString &,const char *);
%End
%If (- Qt_2_00)
	QImageIO(const char *,const char *);
%End

	const QImage &image() const;
	int status() const;
	const char *format() const;
	QIODevice *ioDevice() const;
%If (Qt_2_00 -)
	QString fileName() const;
%End
%If (- Qt_2_00)
	const char *fileName() const;
%End
%If (Qt_3_0_0 -)
	int quality() const;
%End
%If (Qt_2_00 -)
	QString description() const;
%End
%If (- Qt_2_00)
	const char *description() const;
%End
	const char *parameters() const;
%If (Qt_3_0_0 -)
	float gamma() const;
%End

	void setImage(const QImage &);
	void setStatus(int);
	void setFormat(const char *);
	void setIODevice(QIODevice *);
%If (Qt_2_00 -)
	void setFileName(const QString &);
%End
%If (- Qt_2_00)
	void setFileName(const char *);
%End
%If (Qt_3_0_0 -)
	void setQuality(int);
%End
%If (Qt_2_00 -)
	void setDescription(const QString &);
%End
%If (- Qt_2_00)
	void setDescription(const char *);
%End
	void setParameters(const char *);
%If (Qt_3_0_0 -)
	void setGamma(float);
%End

	bool read();
	bool write();

	static const char *imageFormat(const QString &);
	static const char *imageFormat(QIODevice *);
	static QStrList inputFormats();
	static QStrList outputFormats();

//	static void defineIOHandler(const char *,const char *,const char *,
//				    image_io_handler,image_io_handler);

private:
	QImageIO(const QImageIO &);
};


%If (Qt_2_1_0 -)
%If (Qt_IMAGE_TEXT)

class QImageTextKeyLang
{
%TypeHeaderCode
#include <qimage.h>
%End

public:
	QImageTextKeyLang(const char *,const char *);
	QImageTextKeyLang();

	QCString key;
	QCString lang;
};

%End
%End


%ModuleHeaderCode
const char **PyQt_qt_ListToArray(PyObject *lst);
%End


%ModuleCode
// Convert a list of strings to an array of strings on the heap.  Also used by
// QPixmap.
const char **PyQt_qt_ListToArray(PyObject *lst)
{
	int nstr;
	const char **str, **sp;

	nstr = PyList_Size(lst);

	if ((str = (const char **)sipMalloc(nstr * sizeof (char *))) == NULL)
		return NULL;

	// Convert the list.
	sp = str;

	for (int i = 0; i < nstr; ++i)
	{
		char *s;

		if ((s = PyString_AsString(PyList_GetItem(lst,i))) == NULL)
		{
			sipFree((ANY *)str);
			return NULL;
		}

		*sp++ = s;
	}

	return str;
}
%End