KPixmapIO Class Reference

#include <kpixmapio.h>

Public Types
enum	ShmPolicies { ShmDontKeep , ShmKeepAndGrow }

Public Member Functions
TQPixmap	convertToPixmap (const TQImage &image)
TQImage	convertToImage (const TQPixmap &pixmap)
void	putImage (TQPixmap *dst, int dx, int dy, const TQImage *src)
void	putImage (TQPixmap *dst, const TQPoint &offset, const TQImage *src)
TQImage	getImage (const TQPixmap *src, int sx, int sy, int sw, int sh)
TQImage	getImage (const TQPixmap *src, const TQRect &rect)
void	setShmPolicy (int policy)
void	preAllocShm (int size)

Detailed Description

Fast TQImage to/from TQPixmap conversion.

Author

Geert Jansen janse.nosp@m.n@kd.nosp@m.e.org

Version

$Id$

KPixmapIO implements a fast path for TQPixmap to/from TQImage conversions. It uses the MIT-SHM shared memory extension for this. If this extension is not available, it will fall back to standard Qt methods.

Typical usage:
You can use KPixmapIO for load/saving pixmaps.

KPixmapIO io;
pixmap = io.convertToPixmap(image);
image = io.convertToImage(pixmap);

It also has functionality for partially updating/saving pixmaps, see putImage and getImage.

KPixmapIO vs. Qt speed comparison
Speed measurements were taken. These show that usage of KPixmapIO for images up to a certain threshold size, offers no speed advantage over the Qt routines. Below you can see a plot of these measurements.

Performance of KPixmapIO

The threshold size, amongst other causes, is determined by the shared memory allocation policy. If the policy is ShmDontKeep, the shared memory segment is discarded right after usage, and thus needs to be allocated before each transfer. This introduces a a setup penalty not present when the policy is ShmKeepAndGrow. In this case the shared memory segment is kept and resized when necessary, until the KPixmapIO object is destroyed.

The default policy is ShmDontKeep. This policy makes sense when loading pixmaps once. The corresponding threshold is taken at 5.000 pixels as suggested by experiments. Below this threshold, KPixmapIO will not use shared memory and fall back on the Qt routines.

When the policy is ShmKeepAndGrow, the threshold is taken at 2.000 pixels. Using this policy, you might want to use preAllocShm to pre-allocate a certain amount of shared memory, in order to avoid resizes. This allocation policy makes sense in a multimedia type application where you are constantly updating the screen.

Above a couple times the threshold size, KPixmapIO's and Qt's speed become linear in the number of pixels, KPixmapIO being at least 2, and mostly around 4 times faster than Qt, depending on the screen and image depth.

Speed difference seems to be the most at 16 bpp, followed by 32 and 24 bpp respectively. This can be explained by the relatively poor implementation of 16 bit RGB packing in Qt, while at 32 bpp we need to transfer more data, and thus gain more, than at 24 bpp.

Conclusion:
For large pixmaps, there's a definite speed improvement when using KPixmapIO. On the other hand, there's no speed improvement for small pixmaps. When you know you're only transferring small pixmaps, there's no point in using it.

Definition at line 87 of file kpixmapio.h.

Member Enumeration Documentation

ShmPolicies

enum KPixmapIO::ShmPolicies

Shared memory allocation policies.

Definition at line 142 of file kpixmapio.h.

Member Function Documentation

convertToImage()

TQImage KPixmapIO::convertToImage

(

const TQPixmap &

pixmap

)

Convert a pixmap to an image.

Parameters

pixmap

The pixmap to convert.

Returns

The image.

Definition at line 205 of file kpixmapio.cpp.

convertToPixmap()

TQPixmap KPixmapIO::convertToPixmap

(

const TQImage &

image

)

Convert an image to a pixmap.

Parameters

image

The image to convert.

Returns

The pixmap containing the image.

Definition at line 187 of file kpixmapio.cpp.

getImage() [1/2]

TQImage KPixmapIO::getImage	(	const TQPixmap *	src,
		const TQRect &	rect
	)

This function is identical to the one above.

It only differs in the arguments it accepts.

Definition at line 252 of file kpixmapio.cpp.

getImage() [2/2]

TQImage KPixmapIO::getImage	(	const TQPixmap *	src,
		int	sx,
		int	sy,
		int	sw,
		int	sh
	)

Transfer (a part of) a pixmap to an image.

Parameters

src	The source pixmap.
sx	Source x offset.
sy	Source y offset.
sw	Source width.
sh	Source height.

Returns

The image.

Definition at line 258 of file kpixmapio.cpp.

preAllocShm()

void KPixmapIO::preAllocShm

(

int

size

)

Pre-allocate shared memory.

KPixmapIO will be able to transfer images up to this size without resizing.

Parameters

size	The size of the image in pixels.

Definition at line 897 of file kpixmapio.cpp.

putImage() [1/2]

void KPixmapIO::putImage	(	TQPixmap *	dst,
		const TQPoint &	offset,
		const TQImage *	src
	)

This function is identical to the one above.

It only differs in the arguments it accepts.

Definition at line 217 of file kpixmapio.cpp.

putImage() [2/2]

void KPixmapIO::putImage	(	TQPixmap *	dst,
		int	dx,
		int	dy,
		const TQImage *	src
	)

Bitblt an image onto a pixmap.

Parameters

dst	The destination pixmap.
dx	Destination x offset.
dy	Destination y offset.
src	The image to load.

Definition at line 224 of file kpixmapio.cpp.

setShmPolicy()

void KPixmapIO::setShmPolicy

(

int

policy

)

Set the shared memory allocation policy.

See the introduction for KPixmapIO for a discussion.

Parameters

policy

The alloction policy.

Definition at line 898 of file kpixmapio.cpp.

---

The documentation for this class was generated from the following files:

• kpixmapio.h
• kpixmapio.cpp