\section{KPixmap\-IO Class Reference}
\label{classKPixmapIO}\index{KPixmapIO@{KPixmapIO}}
Fast {\bf QImage} to/from {\bf QPixmap} conversion.  


{\tt \#include $<$kpixmapio.h$>$}

\subsection*{Public Types}
\begin{CompactItemize}
\item 
enum {\bf Shm\-Policies} \{ {\bf Shm\-Dont\-Keep}, 
{\bf Shm\-Keep\-And\-Grow}
 \}
\end{CompactItemize}
\subsection*{Public Member Functions}
\begin{CompactItemize}
\item 
{\bf QPixmap} {\bf convert\-To\-Pixmap} (const {\bf QImage} \&image)
\item 
{\bf QImage} {\bf convert\-To\-Image} (const {\bf QPixmap} \&pixmap)
\item 
void {\bf put\-Image} ({\bf QPixmap} $\ast$dst, int dx, int dy, const {\bf QImage} $\ast$src)
\item 
void {\bf put\-Image} ({\bf QPixmap} $\ast$dst, const {\bf QPoint} \&offset, const {\bf QImage} $\ast$src)
\item 
{\bf QImage} {\bf get\-Image} (const {\bf QPixmap} $\ast$src, int sx, int sy, int sw, int sh)
\item 
{\bf QImage} {\bf get\-Image} (const {\bf QPixmap} $\ast$src, const {\bf QRect} \&rect)
\item 
void {\bf set\-Shm\-Policy} (int policy)
\item 
void {\bf pre\-Alloc\-Shm} (int size)
\end{CompactItemize}


\subsection{Detailed Description}
Fast {\bf QImage} to/from {\bf QPixmap} conversion. 

\begin{Desc}
\item[Author:]Geert Jansen $<${\tt jansen@kde.org}$>$ \end{Desc}
\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]{\bf kpixmapio.h}{\rm (p.\,\pageref{kpixmapio_8h})} 345236 2004-09-09 15:23:55Z dfaure \end{Desc}
\end{Desc}
KPixmap\-IO implements a fast path for {\bf QPixmap} to/from {\bf QImage} conversions. It uses the MIT-SHM shared memory extension for this. If this extension is not available, it will fall back to standard {\bf Qt} methods.

{\bf Typical usage:}\par


You can use KPixmap\-IO for load/saving pixmaps.



\footnotesize\begin{verbatim} KPixmapIO io;
 pixmap = io.convertToPixmap(image);
 image = io.convertToImage(pixmap);
\end{verbatim}
\normalsize


It also has functionality for partially updating/saving pixmaps, see put\-Image and get\-Image.

{\bf KPixmap\-IO vs. {\bf Qt} speed comparison}\par


Speed measurements were taken. These show that usage of KPixmap\-IO for images up to a certain threshold size, offers no speed advantage over the {\bf 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 {\tt Shm\-Dont\-Keep}, 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 {\tt Shm\-Keep\-And\-Grow}. In this case the shared memory segment is kept and resized when necessary, until the KPixmap\-IO object is destroyed.

The default policy is {\tt Shm\-Dont\-Keep}. This policy makes sense when loading pixmaps once. The corresponding threshold is taken at 5.000 pixels as suggested by experiments. Below this threshold, KPixmap\-IO will not use shared memory and fall back on the {\bf Qt} routines.

When the policy is {\tt Shm\-Keep\-And\-Grow}, the threshold is taken at 2.000 pixels. Using this policy, you might want to use pre\-Alloc\-Shm 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, KPixmap\-IO's and Qt's speed become linear in the number of pixels, KPixmap\-IO being at least 2, and mostly around 4 times faster than {\bf 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 {\bf Qt}, while at 32 bpp we need to transfer more data, and thus gain more, than at 24 bpp.

{\bf Conclusion:}\par


For large pixmaps, there's a definite speed improvement when using KPixmap\-IO. 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.

\subsection{Member Enumeration Documentation}
\index{KPixmapIO@{KPixmap\-IO}!ShmPolicies@{ShmPolicies}}
\index{ShmPolicies@{ShmPolicies}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum {\bf KPixmap\-IO::Shm\-Policies}}\label{classKPixmapIO_w2}


Shared memory allocation policies. 



Definition at line 142 of file kpixmapio.h.

\subsection{Member Function Documentation}
\index{KPixmapIO@{KPixmap\-IO}!convertToPixmap@{convertToPixmap}}
\index{convertToPixmap@{convertToPixmap}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QPixmap} KPixmap\-IO::convert\-To\-Pixmap (const {\bf QImage} \& {\em image})}\label{classKPixmapIO_a2}


Convert an image to a pixmap. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em image}]The image to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The pixmap containing the image. \end{Desc}


Definition at line 181 of file kpixmapio.cpp.

References QPixmap::convert\-From\-Image(), QPixmap::height(), put\-Image(), and QPixmap::width().

Referenced by KRoot\-Pixmap::update\-Background().\index{KPixmapIO@{KPixmap\-IO}!convertToImage@{convertToImage}}
\index{convertToImage@{convertToImage}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QImage} KPixmap\-IO::convert\-To\-Image (const {\bf QPixmap} \& {\em pixmap})}\label{classKPixmapIO_a3}


Convert a pixmap to an image. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pixmap}]The pixmap to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The image. \end{Desc}


Definition at line 199 of file kpixmapio.cpp.

References get\-Image(), QImage::height(), and QImage::width().

Referenced by KRoot\-Pixmap::update\-Background().\index{KPixmapIO@{KPixmap\-IO}!putImage@{putImage}}
\index{putImage@{putImage}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KPixmap\-IO::put\-Image ({\bf QPixmap} $\ast$ {\em dst}, int {\em dx}, int {\em dy}, const {\bf QImage} $\ast$ {\em src})}\label{classKPixmapIO_a4}


Bitblt an image onto a pixmap. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dst}]The destination pixmap. \item[{\em dx}]Destination x offset. \item[{\em dy}]Destination y offset. \item[{\em src}]The image to load. \end{description}
\end{Desc}


Definition at line 218 of file kpixmapio.cpp.

References QPixmap::convert\-From\-Image(), QPixmap::height(), QImage::height(), QPixmap::width(), and QImage::width().

Referenced by convert\-To\-Pixmap(), and put\-Image().\index{KPixmapIO@{KPixmap\-IO}!putImage@{putImage}}
\index{putImage@{putImage}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KPixmap\-IO::put\-Image ({\bf QPixmap} $\ast$ {\em dst}, const {\bf QPoint} \& {\em offset}, const {\bf QImage} $\ast$ {\em src})}\label{classKPixmapIO_a5}


This function is identical to the one above. 

It only differs in the arguments it accepts. 

Definition at line 211 of file kpixmapio.cpp.

References put\-Image().\index{KPixmapIO@{KPixmap\-IO}!getImage@{getImage}}
\index{getImage@{getImage}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QImage} KPixmap\-IO::get\-Image (const {\bf QPixmap} $\ast$ {\em src}, int {\em sx}, int {\em sy}, int {\em sw}, int {\em sh})}\label{classKPixmapIO_a6}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em src}]The source pixmap. \item[{\em sx}]Source x offset. \item[{\em sy}]Source y offset. \item[{\em sw}]Source width. \item[{\em sh}]Source height. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The image. \end{Desc}


Definition at line 252 of file kpixmapio.cpp.

References QPixmap::convert\-To\-Image(), QImage::height(), and QImage::width().

Referenced by convert\-To\-Image(), and get\-Image().\index{KPixmapIO@{KPixmap\-IO}!getImage@{getImage}}
\index{getImage@{getImage}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QImage} KPixmap\-IO::get\-Image (const {\bf QPixmap} $\ast$ {\em src}, const {\bf QRect} \& {\em rect})}\label{classKPixmapIO_a7}


This function is identical to the one above. 

It only differs in the arguments it accepts. 

Definition at line 246 of file kpixmapio.cpp.

References get\-Image().\index{KPixmapIO@{KPixmap\-IO}!setShmPolicy@{setShmPolicy}}
\index{setShmPolicy@{setShmPolicy}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KPixmap\-IO::set\-Shm\-Policy (int {\em policy})}\label{classKPixmapIO_a8}


Set the shared memory allocation policy. 

See the introduction for KPixmap\-IO for a discussion. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em policy}]The alloction policy. \end{description}
\end{Desc}


Definition at line 892 of file kpixmapio.cpp.\index{KPixmapIO@{KPixmap\-IO}!preAllocShm@{preAllocShm}}
\index{preAllocShm@{preAllocShm}!KPixmapIO@{KPixmap\-IO}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KPixmap\-IO::pre\-Alloc\-Shm (int {\em size})}\label{classKPixmapIO_a9}


Pre-allocate shared memory. 

KPixmap\-IO will be able to transfer images up to this size without resizing. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em size}]The size of the image in {\tt pixels}. \end{description}
\end{Desc}


Definition at line 891 of file kpixmapio.cpp.

The documentation for this class was generated from the following files:\begin{CompactItemize}
\item 
kpixmapio.h\item 
kpixmapio.cpp\end{CompactItemize}
