class KPixmapIO

# class KPixmapIO | Fast QImage to/from QPixmap conversion. More...
Definition | `#include <kpixmapio.h>`
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Types

- enum ShmPolicies { ShmDontKeep, ShmKeepAndGrow }
- enum ByteOrders { bo32_ARGB, bo32_BGRA, bo24_RGB, bo24_BGR, bo16_RGB_565, bo16_BGR_565, bo16_RGB_555, bo16_BGR_555, bo8 }

#### Public Methods

- KPixmapIO ()
- ~KPixmapIO ()
- QPixmap convertToPixmap (const QImage &image)
- QImage convertToImage (const QPixmap &pixmap)
- void putImage (QPixmap *dst, int dx, int dy, const QImage *src)
- void putImage (QPixmap *dst, const QPoint &offset, const QImage *src)
- QImage getImage (const QPixmap *src, int sx, int sy, int sw, int sh)
- QImage getImage (const QPixmap *src, const QRect &rect)
- void setShmPolicy (int policy)
- void preAllocShm (int size)
- bool initXImage (int w, int h)
- void doneXImage ()
- bool createXImage (int w, int h)
- void destroyXImage ()
- bool createShmSegment (int size)
- void destroyShmSegment ()
- void convertToXImage (const QImage &)
- QImage convertFromXImage ()

#### Public Members

- bool m_bShm

## Detailed Description

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.

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.

KPixmapIO () | ### KPixmapIO

~KPixmapIO () | ### ~KPixmapIO

QPixmap convertToPixmap (const QImage &image) | ### convertToPixmap

Convert an image to a pixmap.

Parameters:

image | The image to convert.

Returns: The pixmap containing the image.

QImage convertToImage (const QPixmap &pixmap) | ### convertToImage

Convert a pixmap to an image.

Parameters:

pixmap | The pixmap to convert.

Returns: The image.

void putImage (QPixmap *dst, int dx, int dy, const QImage *src) | ### putImage

Bitblt an image onto a pixmap.

Parameters:

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

void putImage (QPixmap *dst, const QPoint &offset, const QImage *src) | ### putImage

This function is identical to the one above. It only differs in the arguments it accepts.

QImage getImage (const QPixmap *src, int sx, int sy, int sw, int sh) | ### getImage

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.

QImage getImage (const QPixmap *src, const QRect &rect) | ### getImage

This function is identical to the one above. It only differs in the arguments it accepts.

enum ShmPolicies { ShmDontKeep, ShmKeepAndGrow } | ### ShmPolicies

Shared memory allocation policies.

void setShmPolicy (int policy) | ### setShmPolicy

Set the shared memory allocation policy. See the introduction for KPixmapIO for a discussion.

Parameters:

policy | The alloction policy.

void preAllocShm (int size) | ### preAllocShm

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`.

enum ByteOrders { bo32_ARGB, bo32_BGRA, bo24_RGB, bo24_BGR, bo16_RGB_565, bo16_BGR_565, bo16_RGB_555, bo16_BGR_555, bo8 } | ### ByteOrders

bool m_bShm | ### m_bShm

bool initXImage (int w, int h) | ### initXImage

void doneXImage () | ### doneXImage

bool createXImage (int w, int h) | ### createXImage

void destroyXImage () | ### destroyXImage

bool createShmSegment (int size) | ### createShmSegment

void destroyShmSegment () | ### destroyShmSegment

void convertToXImage (const QImage &) | ### convertToXImage

QImage convertFromXImage () | ### convertFromXImage

- Version: $Id: kpixmapio.h,v 1.8.2.2 2003/06/05 23:42:37 mueller Exp $
- Author: Geert Jansen
- Generated: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:37 2003, using kdoc 2.0a54.