kdeui Library API Documentation

KPixmapIO Class Reference

Fast QImage to/from QPixmap conversion. More...

#include <kpixmapio.h>

List of all members.

Public Types

enum  ShmPolicies
 Shared memory allocation policies. More...


Public Methods

QPixmap convertToPixmap (const QImage &image)
 Convert an image to a pixmap.

QImage convertToImage (const QPixmap &pixmap)
 Convert a pixmap to an image.

void putImage (QPixmap *dst, int dx, int dy, const QImage *src)
 Bitblt an image onto a pixmap.

void putImage (QPixmap *dst, const QPoint &offset, const QImage *src)
 This function is identical to the one above.

QImage getImage (const QPixmap *src, int sx, int sy, int sw, int sh)
 Transfer (a part of) a pixmap to an image.

QImage getImage (const QPixmap *src, const QRect &rect)
 This function is identical to the one above.

void setShmPolicy (int policy)
 Set the shared memory allocation policy.

void preAllocShm (int size)
 Pre-allocate shared memory.


Detailed Description

Fast QImage to/from QPixmap conversion.

Author:
Geert Jansen <jansen@kde.org>
Version:
Id:
kpixmapio.h,v 1.8 2002/08/01 14:19:53 coolo Exp

KPixmapIO implements a fast path for QPixmap to/from QImage 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.

kpixmapio-perf.png

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 84 of file kpixmapio.h.


Member Enumeration Documentation

enum KPixmapIO::ShmPolicies
 

Shared memory allocation policies.

Definition at line 139 of file kpixmapio.h.


Member Function Documentation

QPixmap KPixmapIO::convertToPixmap const QImage   image
 

Convert an image to a pixmap.

Parameters:
image  The image to convert.
Returns:
The pixmap containing the image.

Definition at line 177 of file kpixmapio.cpp.

References QPixmap::convertFromImage(), QImage::depth(), QImage::height(), putImage(), and QImage::width().

Referenced by KRootPixmap::updateBackground().

QImage KPixmapIO::convertToImage const QPixmap   pixmap
 

Convert a pixmap to an image.

Parameters:
pixmap  The pixmap to convert.
Returns:
The image.

Definition at line 195 of file kpixmapio.cpp.

References QPixmap::convertToImage(), getImage(), QPixmap::height(), and QPixmap::width().

Referenced by KRootPixmap::updateBackground().

void KPixmapIO::putImage QPixmap   dst,
int    dx,
int    dy,
const QImage   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 214 of file kpixmapio.cpp.

References QPixmap::convertFromImage(), QImage::depth(), QPixmap::height(), QImage::height(), QPixmap::width(), and QImage::width().

Referenced by convertToPixmap(), and putImage().

void KPixmapIO::putImage QPixmap   dst,
const QPoint   offset,
const QImage   src
 

This function is identical to the one above.

It only differs in the arguments it accepts.

Definition at line 207 of file kpixmapio.cpp.

References putImage(), QPoint::x(), and QPoint::y().

QImage KPixmapIO::getImage const QPixmap   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 247 of file kpixmapio.cpp.

References QPixmap::convertToImage(), QPixmap::height(), and QPixmap::width().

Referenced by convertToImage(), and getImage().

QImage KPixmapIO::getImage const QPixmap   src,
const QRect   rect
 

This function is identical to the one above.

It only differs in the arguments it accepts.

Definition at line 241 of file kpixmapio.cpp.

References getImage(), QRect::height(), QRect::width(), QRect::x(), and QRect::y().

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 840 of file kpixmapio.cpp.

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 839 of file kpixmapio.cpp.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:21:07 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001