Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members

CascadeBitmap Class Reference

base class of drawable objects More...

#include <cascade/graphics/CascadeBitmap.h>

Inheritance diagram for CascadeBitmap:

CascadeObject CascadeScreen List of all members.

Public Types

enum  RamType { kVRAMOnly = 0, kMainRAMOnly = 1, kEither = 2 }

Public Member Functions

 CascadeBitmap ()
virtual ~CascadeBitmap ()
virtual bool Create (const CascadeDims &dims, RamType ramType=kEither)
virtual bool CreateFromBitmapFile (CascadeFile &bitmapFile, RamType ramType=kEither)
virtual bool Destroy ()
CascadeRect GetClipRect () const
void SetClipRect (const CascadeRect &rect)
virtual void FrameRect (const CascadeRect &rect, const CascadeColor &color)
virtual void FillRect (const CascadeRect &rect, const CascadeColor &color)
virtual void DrawLine (const CascadePoint &start, const CascadePoint &end, const CascadeColor &color)
virtual void TextOut (const CascadePoint &point, const CascadeString &string, const CascadeFont &font, const CascadeColor &color, u32 nFlags=TEXTOUT_TOP)
virtual bool DrawText (CascadeFont &font, const CascadeRect &rect, const CascadeString &string, const CascadeColor &color, u32 nFlags)
virtual void Blit (const CascadePoint &point, const CascadeBitmap &source, const CascadeRect &sourceRect)
virtual void Blit (const CascadePoint &point, CascadeSharedMemZone &sourceZone, u32 nZoneOffset, u32 nPixelWidth, u32 nPixelHeight, u32 nBitDepth, const CascadeRect &sourceRect)
virtual bool GrabBits (const CascadeRect &sourceRect, CascadeSharedMemZone &destZone, u32 nZoneOffset)
virtual void GetPixel (const CascadePoint &point, CascadeColor &colorToSet) const
virtual void SetPixel (const CascadePoint &point, const CascadeColor &color)
virtual CascadeDims GetDims () const
CascadeRect GetRect () const
virtual u8 GetColorDepth () const
virtual void * GetMemory ()
virtual void Flush ()

Protected Attributes

CascadeRect m_clipRect

Friends

class CascadeScreen

Detailed Description

base class of drawable objects

Skip the description

CascadeBitmap is the base class of drawable objects in Cascade. Clients draw directly onto CascadeBitmaps or their subclasses. The base class of CascadeBitmap implements in-memory bitmaps. These in-memory bitmaps are always created in the color format of the display. While non-traditional, this greatly simplifies both the interface and implementation and provides the functionality needed for the UI in the highest performance possible way while maximizing the ability to meet the schedule. Future versions of the Cascade library will likely support managing multiple formats of in-memory bitmap data, blitting between them etc. For now, clients need not worry about pixel format translation - the implementation handles and hides the actual pixel format from the client.

Note:
general ordering of parameters to the drawing methods are: a. destination location (either point or rect) b. function specific operands c. the color operand, where applicable

All drawing functions clip to the bitmap.

class CascadeBitmap

Member Enumeration Documentation

enum CascadeBitmap::RamType
 

represents a type of RAM used for bitmap creation

RamType is used as an argument to the Create() functions.

See also:
Create(), CreateFromBitmapFile()
Enumeration values:
kVRAMOnly  use video ram only
kMainRAMOnly  use main system ram only
kEither  use whatever ram is available

Constructor & Destructor Documentation

CascadeBitmap::CascadeBitmap (   ) 
 

The CascadeBitmap constructor - lightweight.

This base class constructor is lightweight.

virtual CascadeBitmap::~CascadeBitmap (   )  [virtual]
 

Destructor.

This destructor will automatically Destroy() the bitmap if it has been Created().

Member Function Documentation

virtual void CascadeBitmap::Blit (  const CascadePoint &  point,
CascadeSharedMemZone &  sourceZone,
u32  nZoneOffset,
u32  nPixelWidth,
u32  nPixelHeight,
u32  nBitDepth,
const CascadeRect &  sourceRect
)  [virtual]
 

copies bits from a shared memory zone to the bitmap

This version of Blit() operates on a source bitmap that is contained in a CascadeSharedMemZone and defined by the following parameters:

Parameters:
point the destination point where to place the copied bits
sourceZone the shared memory zone to copy bits from
nZoneOffset the byte offset from the start of the zone where the bitmap bits start
nPixelWidth the width in pixels of the source bitmap
nPixelHeight the height in pixels of the source bitmap
nBitDepth the number of bits per pixel of the bits in the source bitmap
sourceRect the source rectangle of bits to be copied from the sourceZone
Note:
Currently the only pixel format supported is 32bpp RGBA.

the sourceZone passed in must be an Open() zone, but not MapLocked().

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::Blit (  const CascadePoint &  point,
const CascadeBitmap &  source,
const CascadeRect &  sourceRect
)  [virtual]
 

copies bits from bitmap to bitmap

Blit does a simple SRCCOPY bit block transfer from the sourceRect on the bitmap described by source to the destination point.

Parameters:
point the destination point where to place the copied bits
source the source bitmap containing the bits to be copied
sourceRect the source rectangle of bits to be copied from the source bitmap

Reimplemented in CascadeScreen.

virtual bool CascadeBitmap::Create (  const CascadeDims &  dims,
RamType  ramType = kEither
)  [virtual]
 

creates a bitmap

Create() creates an in memory bitmap using the same color depth and format as the screen returning true if successful, false otherwise. The bitmap bits are left uninitialized. Create() returns true if successful, false otherwise. The ramType parameter allows you to specify what type of memory should be used for bitmap creation.

Parameters:
dims the dimensions of the bitmap
ramType the type of ram to be used for the bitmap
Returns:
whether or not the creation succeeded
See also:
Destroy()

CreateFromBitmapFile()

virtual bool CascadeBitmap::CreateFromBitmapFile (  CascadeFile &  bitmapFile,
RamType  ramType = kEither
)  [virtual]
 

creates a bitmap from a file

CreateFromBitmapFile() creates an in memory bitmap using the dimensions of the bitmap located in bitmapFile. The bitmap is created using the same color depth and format as the screen and is initialized with the bitmap data from bitmapFile. CreateFromBitmapFile() automatically converts the file data format into the CascadeBitmap in memory data format. Currently only JPEG image loading is supported. CreateFromBitmapFile() returns true if successful, false otherwise. The ramType parameter allows you to specify what type of memory should be used for bitmap creation.

Parameters:
bitmapFile the file to create the bitmap from
ramType the type of ram to be used for the bitmap
Returns:
whether or not the creation succeeded
See also:
Destroy()

Create()

virtual bool CascadeBitmap::Destroy (   )  [virtual]
 

destroys a previously created bitmap

call Destroy() to destroy a previously created bitmap. Destroy() returns true if destruction was successful or not needed, false if destruction failed (leaving the bitmap in a created state).

Returns:
whether or not the destruction succeeded
See also:
Create(), CreateFromBitmapFile()

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::DrawLine (  const CascadePoint &  start,
const CascadePoint &  end,
const CascadeColor &  color
)  [virtual]
 

draws a 1 pixel line

DrawLine() draws a 1 pixel width line from start to end in the color color

Parameters:
start the starting point of the line
end the ending point of the line
color the color to draw the line with

Reimplemented in CascadeScreen.

virtual bool CascadeBitmap::DrawText (  CascadeFont &  font,
const CascadeRect &  rect,
const CascadeString &  string,
const CascadeColor &  color,
u32  nFlags
)  [virtual]
 

formats and draws a text string on the bitmap

DrawText() is a text rendering primitive that allows the client to specify alignment, clipping, and wrapping of the text string. The output text is positioned relative to rectangle rect. 

		    The following flags are supported:
		    TEXT_CENTER_VERTICALLY
		    TEXT_CENTER_HORIZONTALLY
		    TEXT_JUSTIFY_LEFT
		    TEXT_JUSTIFY_TOP
		    TEXT_JUSTIFY_BOTTOM
		    TEXT_JUSTIFY_RIGHT
		    TEXT_WORD_WRAP
		    TEXT_CLIP
		    TEXT_CLIP_WITH_DOTDOTDOT
		    TEXT_MEASURE_ONLY
Parameters:
font the font to use to output the text
rect the rect with which to position the text
string the text to output
color the color to use to output the text
nFlags the flags to use TEXT_CENTER_VERTICALLY
See also:
TEXT_CENTER_HORIZONTALLY, TEXT_JUSTIFY_LEFT, TEXT_JUSTIFY_TOP, TEXT_JUSTIFY_BOTTOM, TEXT_JUSTIFY_RIGHT, TEXT_WORD_WRAP, TEXT_CLIP, TEXT_CLIP_WITH_DOTDOTDOT, TEXT_MEASURE_ONLY

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::FillRect (  const CascadeRect &  rect,
const CascadeColor &  color
)  [virtual]
 

fills a rectangle with a color

FillRect() fills the rectangle described by rect with the color color

Parameters:
rect the rectangle to fill
color the color to fill the rectangle with
See also:
FrameRect()

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::Flush (   )  [virtual]
 

flushes the pipeline of graphics drawing calls

Flush() flushes the pipeline of graphics calls. It should only be needed in certain circumstances when writing to graphics memory directly.

See also:
CascadeScreen::GetMemory()

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::FrameRect (  const CascadeRect &  rect,
const CascadeColor &  color
)  [virtual]
 

draws a 1 pixel wide rectangle frame

FrameRect() draws the 1-pixel outline of the rectangle described by rect with the color color

Parameters:
rect the rectangle to draw
color the color to draw the rectangle
See also:
FillRect()

Reimplemented in CascadeScreen.

CascadeRect CascadeBitmap::GetClipRect (   )  const [inline]
 

gets the clipping rect for the bitmap

CascadeBitmaps support a clipping rectangle. In Create() the clipping rectangle is initialized to the size of the entire bitmap. call GetClipRect() to get the current clipping rectangle of the bitmap. Note that in Cascade v. 1.0 clipping is not implemented, however the Cascade Windowing system uses the clipping rectangle of the screen so that it can optimize screen drawing.

Returns:
the clipping rectangle
See also:
SetClipRect()

virtual u8 CascadeBitmap::GetColorDepth (   )  const [virtual]
 

gets the color depth of the bitmap in bits-per-pixel

GetColorDepth() returns the color depth of the bitmap in bits per pixel.

Returns:
the color depth of the bitmap in bits per pixel

Reimplemented in CascadeScreen.

virtual CascadeDims CascadeBitmap::GetDims (   )  const [virtual]
 

gets the dimensions of the bitmap

GetDims() returns the dimensions of the bitmap.

Returns:
the dimensions of the bitmap

Reimplemented in CascadeScreen.

virtual void* CascadeBitmap::GetMemory (   )  [virtual]
 

returns a pointer to the bitmap's memory

GetMemory() is currently not implemented and always returns NULL. It will be implemented in the future.

Returns:
NULL
See also:
CascadeScreen::GetMemory() (which is implemented).

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::GetPixel (  const CascadePoint &  point,
CascadeColor &  colorToSet
)  const [virtual]
 

gets the color of a pixel located at a specific point

GetPixel() sets colorToSet with the color value of the pixel located at point.

Parameters:
point the point of the pixel to retrieve
colorToSet a reference to the
See also:
SetPixel()

Reimplemented in CascadeScreen.

CascadeRect CascadeBitmap::GetRect (   )  const [inline]
 

returns the rectangle dimensions the bitmap

GetRect() returns a rectangle the width and height of the bitmap located at (x = 0, y = 0).

Returns:
the rectangle describing the bitmap

virtual bool CascadeBitmap::GrabBits (  const CascadeRect &  sourceRect,
CascadeSharedMemZone &  destZone,
u32  nZoneOffset
)  [virtual]
 

copies bits from the bitmap to a shared memory zone

GrabBits() copies bits from the sourceRect of this bitmap to the shared memory zone identified by destZone using the following parameters. If GrabBits() returns true, sourceRect.w * sourceRect.h 32bit RGBA words were copied to destZone starting at nZoneOffset.

Parameters:
sourceRect the rectangle on this bitmap to grab bits from
sourceZone the shared memory zone to copy bits top
nZoneOffset the byte offset from the start of the zone where the bitmap bits should be copied
Note:
Currently the only pixel format supported is 32bpp RGBA.

the sourceZone passed in must be an Open() zone, but not MapLocked().

Reimplemented in CascadeScreen.

void CascadeBitmap::SetClipRect (  const CascadeRect &  rect  ) 
 

sets the clipping rect for the bitmap

Call SetClipRect() to set the current clipping rectangle of the bitmap. All drawing will be clipped to this rectangle (though this is not implemented in Cascade v. 1.0). NOTE: good programming practices dicate that if you set the clip rect you should restore it to what it was before you set it when you are done with whatever you are doing. The rect passed in to SetClipRect will be normalized to the bounding rectangle of the bitmap. If the rect falls outside of the bitmap rectangle, The clip rect will be set to (0, 0, 0, 0).

Parameters:
rect the new clipping rectangle
See also:
GetClipRect()

virtual void CascadeBitmap::SetPixel (  const CascadePoint &  point,
const CascadeColor &  color
)  [virtual]
 

sets the color for a pixel located at a specific point

SetPixel() sets the pixel located at point with the color value of color.

Parameters:
point the point of the pixel to set
color the color value for the pixel to set
See also:
GetPixel()

Reimplemented in CascadeScreen.

virtual void CascadeBitmap::TextOut (  const CascadePoint &  point,
const CascadeString &  string,
const CascadeFont &  font,
const CascadeColor &  color,
u32  nFlags = TEXTOUT_TOP
)  [virtual]
 

draws a text string on the bitmap

TextOut() is a simple text output function that outputs the string string in the font font in the color color at the location point.

Reimplemented in CascadeScreen.

Friends And Related Function Documentation

friend class CascadeScreen [friend]
 

Member Data Documentation

CascadeRect CascadeBitmap::m_clipRect [protected]
 

The documentation for this class was generated from the following file:
Generated on Sun Jul 24 14:27:18 2005 for Cascade Library by  doxygen 1.4.1