org.kde.koala
Class KPixmapIO

java.lang.Object
  extended by org.kde.koala.KPixmapIO
All Implemented Interfaces:
org.kde.qt.QtSupport

public class KPixmapIO
extends java.lang.Object
implements org.kde.qt.QtSupport

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\n 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.

    Version:
    $Id: KPixmapIO.java 473384 2005-10-23 14:17:09Z rdale $
    Author:
    Geert Jansen

    Field Summary
    static int ShmDontKeep
              Shared memory allocation policies.
    static int ShmKeepAndGrow
               
     
    Constructor Summary
      KPixmapIO()
               
    protected KPixmapIO(java.lang.Class dummy)
               
     
    Method Summary
     org.kde.qt.QImage convertToImage(org.kde.qt.QPixmap pixmap)
              Convert a pixmap to an image.
     org.kde.qt.QPixmap convertToPixmap(org.kde.qt.QImage image)
              Convert an image to a pixmap.
     void dispose()
              Delete the wrapped C++ instance ahead of finalize()
    protected  void finalize()
              Deletes the wrapped C++ instance
     org.kde.qt.QImage getImage(org.kde.qt.QPixmap src, int sx, int sy, int sw, int sh)
              Transfer (a part of) a pixmap to an image.
     org.kde.qt.QImage getImage(org.kde.qt.QPixmap src, org.kde.qt.QRect rect)
              This function is identical to the one above.
     boolean isDisposed()
              Has the wrapped C++ instance been deleted?
     void preAllocShm(int size)
              Pre-allocate shared memory.
     void putImage(org.kde.qt.QPixmap dst, int dx, int dy, org.kde.qt.QImage src)
              Bitblt an image onto a pixmap.
     void putImage(org.kde.qt.QPixmap dst, org.kde.qt.QPoint offset, org.kde.qt.QImage src)
              This function is identical to the one above.
     void setShmPolicy(int policy)
              Set the shared memory allocation policy.
     
    Methods inherited from class java.lang.Object
    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    ShmDontKeep

    public static final int ShmDontKeep
    Shared memory allocation policies.

    See Also:
    Constant Field Values

    ShmKeepAndGrow

    public static final int ShmKeepAndGrow
    See Also:
    Constant Field Values
    Constructor Detail

    KPixmapIO

    protected KPixmapIO(java.lang.Class dummy)

    KPixmapIO

    public KPixmapIO()
    Method Detail

    convertToPixmap

    public org.kde.qt.QPixmap convertToPixmap(org.kde.qt.QImage image)
    Convert an image to a pixmap.

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

    convertToImage

    public org.kde.qt.QImage convertToImage(org.kde.qt.QPixmap pixmap)
    Convert a pixmap to an image.

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

    putImage

    public void putImage(org.kde.qt.QPixmap dst,
                         int dx,
                         int dy,
                         org.kde.qt.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.

    putImage

    public void putImage(org.kde.qt.QPixmap dst,
                         org.kde.qt.QPoint offset,
                         org.kde.qt.QImage src)
    This function is identical to the one above. It only differs in the arguments it accepts.


    getImage

    public org.kde.qt.QImage getImage(org.kde.qt.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.

    getImage

    public org.kde.qt.QImage getImage(org.kde.qt.QPixmap src,
                                      org.kde.qt.QRect rect)
    This function is identical to the one above. It only differs in the arguments it accepts.


    setShmPolicy

    public void setShmPolicy(int policy)
    Set the shared memory allocation policy. See the introduction for KPixmapIO for a discussion.

    Parameters:
    policy - The alloction policy.

    preAllocShm

    public void 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.

    finalize

    protected void finalize()
                     throws java.lang.InternalError
    Deletes the wrapped C++ instance

    Overrides:
    finalize in class java.lang.Object
    Throws:
    java.lang.InternalError

    dispose

    public void dispose()
    Delete the wrapped C++ instance ahead of finalize()


    isDisposed

    public boolean isDisposed()
    Has the wrapped C++ instance been deleted?