Main Page   Class Hierarchy   Compound List   File List   Compound Members  

ZSurface Class Reference

The ZSurface class is a memory area to which you can draw images and primitives. More...

#include <ZSurface.h>

Inheritance diagram for ZSurface:

ZFont List of all members.

Public Types

enum  ZROTATION { Z0, Z90, Z270 }

Public Methods

 ZSurface ()
 ZSurface (int w, int h, bool alpha=false)
 ZSurface (const QImage &img, bool alpha=false)
 ZSurface (const QPixmap &pix, bool alpha=false)
 ZSurface (const ZSurface &)
virtual ~ZSurface ()
ZSurface & operator= (const ZSurface &z)
virtual bool create (const QImage &, bool alpha=false)
virtual bool create (const QPixmap &, bool alpha=false)
virtual bool create (int width, int height, bool alpha=false)
void fill (QColor clr)
bool drawLine (int x1, int y1, int x2, int y2, QColor clr)
bool drawLineBlend (int x1, int y1, int x2, int y2, QColor clr, int opacity)
int ZSurface::drawText (int dx, int ny, const QString &s, ZFont *f, int opacity=32)
int ZSurface::drawText (int dx, int ny, const QString &s, ZFont *f, QColor c, int opacity=32)
bool isValid () const
bool hasAlpha () const
int width () const
int size () const
int scanlineWidth () const
int height () const
int depth () const
void setPixel (int x, int y, const QColor &c)
void getPixel (int x, int y, QColor &c)
unsigned short * bits ()
unsigned short * alpha ()

Static Public Methods

ZROTATION rotation ()
void setRotation (ZROTATION zr)
bool bitBlit (QDirectPainter *dst, const ZSurface *src, ZROTATION r)
bool bitBlit (ZSurface *dst, int dx, int dy, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool bitBlitBlend (int opacity, ZSurface *dst, int dx, int dy, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool bitBlitAlpha (ZSurface *dst, int dx, int dy, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool bitBlitKeyed (ZSurface *dst, int dx, int dy, const QColor &key, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool bitBlitKeyedBlend (int opacity, ZSurface *dst, int dx, int dy, const QColor &key, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool fillBlitKeyed (ZSurface *dst, int dx, int dy, const QColor &key, const QColor &fillColor, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool fillBlitKeyedBlend (int opacity, ZSurface *dst, int dx, int dy, const QColor &key, const QColor &fillColor, const ZSurface *src, int sx=0, int sy=0, int sw=-1, int sh=-1)
bool fillRect (ZSurface *dst, int dx, int dy, int rw, int rh, const QColor &clr)
bool fillRectBlend (int opacity, ZSurface *dst, int dx, int dy, int rw, int rh, const QColor &clr)

Protected Methods

void initFromImage (const QImage &i)

Detailed Description

The ZSurface class is a memory area to which you can draw images and primitives.

It provides set of optimized methods for various types of memory transfers ( blitting) between memory buffers (ZSurfaces) and/or framebuffer (video) memory on ARM powered, qte based devices.
Each ZSurface object has a memory buffer associated with it and , optionally, a alpha channel buffer which specifies the transparency of a pixel. 0 means completely transparent and 255 means opaque.
A surface has the parameters width(), height() and the actual pixels and alpha data.
It can be initialized using an existing QImage or QPixmap object.
Generally there are two kinds of methods available:

Every transfer (blit) method as well as primitives drawing methods (lines and text) with exception of setPixel() getPixel() perform internal clipping/parameter validation before each operation.
Usage:
This class was designed with a single goal - fast, optimized memory transfers between memory surfaces and/or framebuffer memory.
Nothing more, nothing less.
This is not a "game programming library" - SDL or Allegro style. There is absolutely no provision for any sort of event handling or anything else beyond video operations.
You can think of it as an extension to QPainter class. It can be incorporated into qte based applications, SDL or whatever else suits you best. The only limitation is that you need to be able to supply a valid QDirectPainter object ( which is used to obtain pointer to a framebuffer memory.)
If you were to a write a qte application using this class, generally you would write your code like this:

1) You would create your main window ( just like any other qte based application.)
2) At this point ZSurface only supports full-screen application/games and therefore your next step would be to switch your application into full screen mode ( refer to the example code or this page for more information about this subject)
3) Next you would create backbuffer ZSurface which MUST be the same size as your screen (240x320 at this point.)
4) Load/create all other ZSurfaces for your sprites/objects etc ...
5) Create some sort of heartbeat function ( for example using QTimer) and draw all your images/sprites in that method using backbuffer surface as a destination.
6) At the end of that method call bitBlit(QDirectPainter *dst, const ZSurface *src,ZROTATION r) giving as a src your backbuffer surface.
This will blit content of your backbuffer to the framebuffer memory (display.)

Of course, as mentioned above you are free to do write any sort of code you want - as long as you can get your hands on QDirectPainter object to use it in your final blit to the screen memory, you are fine.

TO DO:

Member Enumeration Documentation

enum ZSurface::ZROTATION
 

Enumeration values:
Z0 
Z90 
Z270 

Constructor & Destructor Documentation

ZSurface::ZSurface (    ) 
 

Constructs an invalid (null) ZSurface object.

ZSurface::ZSurface (  int    w,
int    h,
bool    alpha = false
) 
 

Constructs a ZSurface object with w width, h height and alpha=false.

ZSurface::ZSurface (  const QImage &    img,
bool    alpha = false
) 
 

Constructs a ZSurface out of a valid QImage object. If alpha is set to true and the img object contains alpha channel data, this information will retained by the object (and later used by bitBlitAlpha.)

ZSurface::ZSurface (  const QPixmap &    pix,
bool    alpha = false
) 
 

Constructs a ZSurface out of a valid QPixmap object. The Pixmap is used to create QImage object which then in turn is used to create ZSurface

ZSurface::ZSurface (  const ZSurface &    ) 
 

Constructs a deep copy of ZSurface object.

virtual ZSurface::~ZSurface (    )  [virtual]
 

Destroys the object and cleans up

Member Function Documentation

unsigned short* ZSurface::alpha (    )  [inline]
 

Returns a pointer to the alpha channel data.

bool ZSurface::bitBlit (  ZSurface *    dst,
int    dx,
int    dy,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst surface. The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

bool ZSurface::bitBlit (  QDirectPainter *    dst,
const ZSurface *    src,
ZROTATION    r
)  [static]
 

Copies a block of pixels from src to a valid QDirectPainter object using rotation r. The src ZSurface has to have the same size as the destination QDirectPainter object. This method should be used if you want to transfer content of the backbuffer ZSurface ( or any surface that has the same dimensions as the screen ) to the framebuffer (video) memory.
Returns false if the size of the src surface does not match QDirectPainter size.
(fast ASM method)

bool ZSurface::bitBlitAlpha (  ZSurface *    dst,
int    dx,
int    dy,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst surface blending each pixel using alpha channel information from src. If the src surface does not contain alpha channel this call will have the same effect as bitBlit.
The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

bool ZSurface::bitBlitBlend (  int    opacity,
ZSurface *    dst,
int    dx,
int    dy,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst surface, blending each pixel using static alpha value opacity (0-32).
The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

bool ZSurface::bitBlitKeyed (  ZSurface *    dst,
int    dx,
int    dy,
const QColor &    key,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst. For any src pixel matching QColor value key, the coresponding dst pixel will remain unchanged.
The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

bool ZSurface::bitBlitKeyedBlend (  int    opacity,
ZSurface *    dst,
int    dx,
int    dy,
const QColor &    key,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst blending each pixel using static alpha value opacity (0-32). For any src pixel matching QColor value key, the coresponding dst pixel will remain unchanged.
The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

unsigned short* ZSurface::bits (    )  [inline]
 

Returns a pointer to the pixel data.

virtual bool ZSurface::create (  int    width,
int    height,
bool    alpha = false
)  [virtual]
 

Initializes an existing instance of ZSurface object with a given set of parameters. If the existing ZSurface object is a valid one and the size of the ZSurface doesn't change (w*h), the already allocated memory will be reused. If the object is invalid or the new size is different, a new memory block will be allocated and initialized with 0.If set to true,the alpha channel is initialized with 255(opaque)
Returns false if memory allocation failed.

virtual bool ZSurface::create (  const QPixmap &   ,
bool    alpha = false
)  [virtual]
 

Same as create(QImage ..) but using QPixmap as a source. If set to true, the alpha channel is initialized with 255 (opaque)

virtual bool ZSurface::create (  const QImage &   ,
bool    alpha = false
)  [virtual]
 

Initializes an existing instance of ZSurface object from a valid QImage. If the existing ZSurface object is a valid one and the size of the ZSurface doesn't change (w*h), the already allocated memory will be reused. If the object is invalid or the new size is different, a new memory block will be allocated and initialized with content of QImage.
Returns false if memory allocation failed or QImage depth is not 32.

int ZSurface::depth (    )  const [inline]
 

Returns depth of the surface (currently always 16).

bool ZSurface::drawLine (  int    x1,
int    y1,
int    x2,
int    y2,
QColor    clr
) 
 

Draws a line form (x1,y1) to (x2,y2) using the color value clr

bool ZSurface::drawLineBlend (  int    x1,
int    y1,
int    x2,
int    y2,
QColor    clr,
int    opacity
) 
 

Draws a line from (x1,y1) to (x2,y2) blending the color value clr with the existing pixels usign static alpha value opacity.

void ZSurface::fill (  QColor    clr ) 
 

Fills the entire surface with the color value clr (fast method)

bool ZSurface::fillBlitKeyed (  ZSurface *    dst,
int    dx,
int    dy,
const QColor &    key,
const QColor &    fillColor,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst using value of QColor fillColor to replace destination pixel. For any src pixel matching QColor value key,the coresponding dst pixel will remain unchanged.
The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

bool ZSurface::fillBlitKeyedBlend (  int    opacity,
ZSurface *    dst,
int    dx,
int    dy,
const QColor &    key,
const QColor &    fillColor,
const ZSurface *    src,
int    sx = 0,
int    sy = 0,
int    sw = -1,
int    sh = -1
)  [static]
 

Copies a block of pixels from src to dst blending QColor value fillColor with a dst pixel using static alpha value opacity (0-32). For any src pixel matching QColor value key,the coresponding dst pixel will remain unchanged.
The sx,sy is the top left pixel in src (0,0) by default, dx,dy is the top left pixel in dst and sw,sh is the size of src (all of src by default.)
Returns false if any of the surfaces is invalid or the src rectangle does not intersect with the dst rectangle.
(fast ASM method)

bool ZSurface::fillRect (  ZSurface *    dst,
int    dx,
int    dy,
int    rw,
int    rh,
const QColor &    clr
)  [static]
 

Fills the rectangle (dx,dy,rw,rh) with the QColor value clr.
Returns false if the src surface is invalid or the specified rectangle does not intersect witht the surface rectangle.
(fast ASM method)

bool ZSurface::fillRectBlend (  int    opacity,
ZSurface *    dst,
int    dx,
int    dy,
int    rw,
int    rh,
const QColor &    clr
)  [static]
 

Fills the rectangle (dx,dy,rw,rh) blending QColor value fillColor with the src pixels using static alpha value opacity (0-32).
Returns false if the src surface is invalid or the specified rectangle does not intersect witht the surface rectangle.
(fast ASM method)

void ZSurface::getPixel (  int    x,
int    y,
QColor &    c
)  [inline]
 

Retrieves a color value of a single point at (x,y) into QColor reference c.

bool ZSurface::hasAlpha (    )  const [inline]
 

Returns true if this ZSurface object has an alpha buffer associated with it.

int ZSurface::height (    )  const [inline]
 

Returns the height of the surface in pixels.

Reimplemented in ZFont.

void ZSurface::initFromImage (  const QImage &    i )  [protected]
 

bool ZSurface::isValid (    )  const [inline]
 

Returns true if this ZSurface object is valid ( has been properly initialized and has a valid memory block associated with it.)

ZSurface& ZSurface::operator= (  const ZSurface &    z ) 
 

Assigns a deep copy of z to this ZSurface object and returns a reference to it.

ZROTATION ZSurface::rotation (    )  [inline, static]
 

int ZSurface::scanlineWidth (    )  const [inline]
 

Returns the spacing in pixels from one line to the next.
The scan lines are always dword aligned ( 2 pixels) so this value will return width()+1 if during the initialization of the surface the requested width for the surface was not even.

void ZSurface::setPixel (  int    x,
int    y,
const QColor &    c
)  [inline]
 

Draws/Plots a single point at (x,y) using QColor value c.

void ZSurface::setRotation (  ZROTATION    zr )  [inline, static]
 

int ZSurface::size (    )  const [inline]
 

Returns the total size of the surface memory block in bytes ( scanlineWidth()*height()*(depth()/8) ).

int ZSurface::width (    )  const [inline]
 

Returns the width of the surface in pixels.

int ZSurface::ZSurface::drawText (  int    dx,
int    ny,
const QString &    s,
ZFont *    f,
QColor    c,
int    opacity = 32
) 
 

Draws text on the surface using ZFont f, with a color value c, optionally blending with the surface pixels using static alpha opacity (0-32 , default 32 means no blending.)
Returns width of the drawn text in pixels.
(fast ASM method)

int ZSurface::ZSurface::drawText (  int    dx,
int    ny,
const QString &    s,
ZFont *    f,
int    opacity = 32
) 
 

Draws text on the surface using ZFont f, optionally blending with the surface pixels using static alpha opacity (0-32 , default 32 means no blending.)
Returns width of the drawn text in pixels.
(fast ASM method)

The documentation for this class was generated from the following file:
Generated on Mon Feb 24 21:00:44 2003 for ZSurface by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002