Rogue Wave Views
Foundation Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Types | Public Member Functions | Friends
IlvBitmap Class Reference

Port class. More...

#include <ilviews/base/port.h>

Inheritance diagram for IlvBitmap:
IlvSystemPort IlvPort IlvValueInterface

Public Types

enum  MemoryType { NoMemory, VideoMemory, SystemMemory }
 The different types of memory location used by bitmaps. More...
 

Public Member Functions

 IlvBitmap (IlvDisplay *display, IlvDim width, IlvDim height, IlUShort depth, unsigned char *data, IlBoolean bitOrder=IlTrue, IlUShort padding=32)
 Constructor. More...
 
 IlvBitmap (IlvDisplay *display, IlvDim width, IlvDim height, IlUShort depth)
 Constructor. More...
 
 IlvBitmap (IlvDisplay *display, IlvWindowsHandle hBitmap, IlBoolean owner=IlFalse)
 Constructor from an HBITMAP. More...
 
IlBoolean computeMask ()
 Computes the mask of this bitmap. More...
 
IlUShort depth () const
 Retrieves the depth of this bitmap. More...
 
IlvBitmapAnimationHandlergetAnimationHandler () const
 Returns the animation handler connected to this bitmap. More...
 
IlvBitmapgetMask () const
 Retrieves the mask of this bitmap. More...
 
MemoryType getMemoryType () const
 Gets the type of memory used in this bitmap. More...
 
const char * getName () const
 Retrieves the name of this bitmap. More...
 
IlInt getTransparentColorIndex () const
 Retrieves the transparent color of this bitmap. More...
 
virtual IlBoolean isABitmap () const
 Queries the nature of this port. More...
 
void lock ()
 Locks the bitmap. More...
 
virtual IlBoolean save (const char *filename) const
 Saves the bitmap to a file. More...
 
virtual IlBoolean save (ostream &stream) const
 Saves a bitmap to a stream. More...
 
IlBoolean saveAscii (const char *filename) const
 Saves an ASCII representation of this bitmap to a file. More...
 
void setAnimationHandler (IlvBitmapAnimationHandler *handler)
 Sets the animation handler connected to this bitmap. More...
 
void setMask (IlvBitmap *mask)
 Sets the mask of this bitmap. More...
 
void setName (const char *name)
 Sets the name of this bitmap. More...
 
void setTransparentColorIndex (IlInt tcIndex)
 Sets the transparent color of this bitmap. More...
 
void unLock ()
 Unlocks the bitmap. More...
 
void useColor (IlvColor *color)
 Verbose: More...
 
- Public Member Functions inherited from IlvSystemPort
 IlvSystemPort (IlvDisplay *display, IlvWindowsHandle HDC, IlvDim width=0, IlvDim height=0)
 Windows-specific constructor. More...
 
virtual IlBoolean applyValue (const IlvValue &)
 Apply an accessor. More...
 
virtual void clearArea (const IlvRect &, IlBoolean=IlFalse) const
 Clears a rectangular area of the screen. More...
 
virtual void clearArea (const IlvRegion &, IlBoolean=IlFalse) const
 Clears a region of the screen. More...
 
virtual void clip (const IlvRect *) const
 Limits the drawing to the given rectangular area. More...
 
virtual void clip (const IlvRegion *) const
 Limits the drawing to the given region. More...
 
virtual void drawArc (const IlvPalette *, const IlvRect &, IlFloat, IlFloat) const
 Draws an arc. More...
 
virtual void drawBitmap (const IlvPalette *, const IlvSystemPort *, const IlvRect &, const IlvPoint &) const
 Draws an image. More...
 
virtual void drawBitmap (const IlvPalette *, const IlvBitmap *, const IlvRect &, const IlvRegion *=0, IlvPosition=IlvCenter, IlBoolean=IlFalse) const
 Draws an image. More...
 
virtual void drawIString (const IlvPalette *, const IlvPoint &, const char *, int, IlvPosition=IlvLeft) const
 Draws a string at the given position. More...
 
virtual void drawLine (const IlvPalette *, const IlvPoint &, const IlvPoint &) const
 Draws a line between 2 points. More...
 
virtual void drawPoint (const IlvPalette *, const IlvPoint &) const
 Draws a point at the given position. More...
 
virtual void drawPoints (const IlvPalette *, IlUInt, const IlvPoint *) const
 Draws a series of points. More...
 
virtual void drawPolyLine (const IlvPalette *, IlUInt, const IlvPoint *) const
 Draws a series of connected lines. More...
 
virtual void drawPolyLine (const IlvPalette *, const IlvPoint &, IlUInt, const IlvDeltaPoint *) const
 Draws a series of connected lines relatively to a reference. More...
 
virtual void drawRectangle (const IlvPalette *, const IlvRect &) const
 Draws the given rectangle. More...
 
virtual void drawRoundRectangle (const IlvPalette *, const IlvRect &, IlUShort) const
 Draws a round rectangle. More...
 
virtual void drawSegments (const IlvPalette *, IlUInt, const IlvPoint *, const IlvPoint *) const
 Draws a set of segments. More...
 
virtual void drawString (const IlvPalette *, const IlvPoint &, const char *, int, IlvPosition=IlvLeft) const
 Draws a string at the given position. More...
 
virtual void drawTransformedString (const IlvPalette *, const char *, int, const IlvTransformer &, const IlvRegion *=0) const
 Draws a transformed string. More...
 
virtual void drawTransparentBitmap (const IlvPalette *, const IlvSystemPort *, const IlvRect &, const IlvPoint &) const
 Draws a transparent bitmap. More...
 
virtual void end ()
 Closed the dump device. More...
 
virtual void fillArc (const IlvPalette *, const IlvRect &, IlFloat, IlFloat) const
 Fills the arc. More...
 
virtual void fillPaths (const IlvPalette *, IlUInt, const IlvPointArray *) const
 Fills the shape defined by the given paths. More...
 
virtual void fillPolyLine (const IlvPalette *, IlUInt, const IlvPoint *, IlBoolean=IlFalse) const
 Fills a polygon. More...
 
virtual void fillPolyLine (const IlvPalette *, const IlvPoint &, IlUInt, const IlvDeltaPoint *, IlBoolean=IlFalse) const
 Fills a polygon. More...
 
virtual void fillRectangle (const IlvPalette *, const IlvRect &) const
 Fills the given rectangle. More...
 
virtual void fillRoundRectangle (const IlvPalette *, const IlvRect &, IlUShort) const
 Fills a round rectangle. More...
 
IlvWindowsHandle getDC () const
 Gets the Windows Handle Device Context. More...
 
virtual IlBoolean initDevice (const char *, IlvRect *=0)
 Initializes the dump device. More...
 
virtual IlBoolean isASystemPort () const
 Indicates that this port is a true system port (not a dump device). More...
 
virtual IlBoolean isBad () const
 Indicates whether this port is valid. More...
 
virtual IlBoolean newPage () const
 Produces an output page and prepares for a new page. More...
 
void releaseDC ()
 Releases the Windows Handle Device Context. More...
 
virtual void send (const char *) const
 Sends character strings to an output device. More...
 
virtual void setTransformer (const IlvTransformer &)
 Applies another transformer to the coordinates provided for the drawing functions. More...
 
virtual void stretchBitmap (const IlvPalette *, const IlvPoint &, const IlvBitmap *, const IlvTransformer &, const IlvRect *=0) const
 Stretches a bitmap. More...
 
virtual void stretchBitmap (const IlvPalette *, const IlvRect &, const IlvBitmap *, const IlvRect *=0) const
 Stretches a bitmap. More...
 
virtual void stretchBitmapData (const IlvPalette *palette, const IlvBitmapData *src, const IlvRect &from, const IlvRect &to, IlBoolean opaque=IlFalse) const
 Draws a bitmap data. More...
 
virtual void stretchTransparentBitmap (const IlvPalette *, const IlvPoint &, const IlvBitmap *, const IlvTransformer &, const IlvRect *=0) const
 Stretches a transparent bitmap. More...
 
virtual void stretchTransparentBitmap (const IlvPalette *, const IlvRect &, const IlvBitmap *, const IlvRect *=0) const
 Stretches a transparent bitmap. More...
 
- Public Member Functions inherited from IlvPort
 IlvPort (IlvDisplay *display=0)
 Constructor. More...
 
void composeAlpha (IlvIntensity alpha)
 Composes the current alpha value of the port. More...
 
virtual void drawArrow (const IlvPalette *palette, const IlvPoint &from, const IlvPoint &to, IlFloat position) const
 Draws an arrow. More...
 
virtual void drawBezier (const IlvPalette *palette, IlUInt count, const IlvPoint *points) const
 Draws a set of Bézier curves. More...
 
virtual void drawClosedBezier (const IlvPalette *palette, IlUInt count, const IlvPoint *points) const
 Appends a closing curve to a set of Bézier curves. More...
 
virtual void drawILabel (const IlvPalette *palette, const char *label, int length, const IlvRect &drawRect, const IlvRegion *clip=0, IlvPosition align=IlvCenter) const
 Draws a label in a rectangle. More...
 
virtual void drawLabel (const IlvPalette *palette, const char *label, int length, const IlvRect &drawRect, const IlvRegion *clip=0, IlvPosition align=IlvCenter) const
 Draws a label in a rectangle. More...
 
virtual void drawMarker (const IlvPalette *palette, const IlvPoint &location, IlvMarkerType type=IlvMarkerSquare, IlUShort size=IlvDefaultMarkerSize) const
 Draws a marker. More...
 
virtual void drawMnemonicLabel (const IlvPalette *palette, const char *label, const IlvRect &drawRect, const IlvRegion *clip=0, IlvPosition align=IlvCenter, IlBoolean underline=IlTrue) const
 Draws an underlined letter in a label. More...
 
virtual void drawOutlineRectangle (const IlvPalette *outlinePalette, const IlvPalette *fillPalette, const IlvRect &rect, const IlvRegion *clip=0) const
 Draws a rectangle with border effects. More...
 
virtual void drawPaths (const IlvPalette *palette, IlUInt count, const IlvPointArray *paths) const
 Draws an array of paths as polylines. More...
 
virtual void drawReliefDiamond (const IlvPalette *, const IlvPalette *invertedPalette, const IlvPalette *topShade, const IlvPalette *bottomShade, const IlvRect &bbox, IlUShort thickness, const IlvRegion *clip=0) const
 Draws a diamond with depth effects. More...
 
virtual void drawReliefRectangle (const IlvPalette *palette, const IlvPalette *invertedPalette, const IlvPalette *topShade, const IlvPalette *bottomShade, const IlvRect &bbox, IlUShort thickness, const IlvRegion *clip=0) const
 Draws a filled rectangle with depth effects. More...
 
virtual void drawShadowRectangle (const IlvPalette *palette, const IlvPalette *invertedPalette, const IlvRect &bbox, IlUShort thickness, IlvPosition shadowPosition, const IlvRegion *clip=0) const
 Draws a filled rectangle with its shadow. More...
 
virtual void fillBezier (const IlvPalette *palette, IlUInt count, const IlvPoint *points) const
 Fills an area specified by a set of Bézier curves. More...
 
IlvIntensity getAlpha () const
 Provides the alpha value of the port. More...
 
IlvAntialiasingMode getAntialiasingMode () const
 Provides the anti-aliasing mode of the port. More...
 
IlvDisplaygetDisplay () const
 Returns a pointer to the IlvDisplay of this port. More...
 
IlvDim height () const
 Provides the height of the port. More...
 
virtual IlBoolean isADevice () const
 Indicates that this port is a dump device. More...
 
void setAlpha (IlvIntensity alpha)
 Sets the alpha value of the port. More...
 
void setAntialiasingMode (IlvAntialiasingMode mode)
 Sets the anti-aliasing mode of the port. More...
 
void size (IlvDim &w, IlvDim &h) const
 Gives the dimensions of the port. More...
 
IlvDim width () const
 Provides the width of the port. More...
 
- Public Member Functions inherited from IlvValueInterface
virtual IlBoolean changeValue (const IlvValue &val)
 Changes the value of an accessor. More...
 
virtual IlBoolean changeValues (const IlvValue *values, IlUShort count=0)
 Changes several accessor values simultaneously. More...
 
virtual void getAccessors (const IlSymbol *const **names, const IlvValueTypeClass *const **types, IlUInt &count) const
 Retrieves the list of available accessors of an object. More...
 
virtual IlvValuequeryValue (IlvValue &val) const
 Retrieves an accessor value. More...
 
virtual void queryValues (IlvValue *values, IlUShort count) const
 Retrieves multiple accessor values simultaneously. More...
 

Friends

class IlvDisplay
 

Additional Inherited Members

- Static Public Member Functions inherited from IlvSystemPort
static IlvBitmapDataGetBitmapData (IlvSystemPort *port, const IlvRect *rect=0)
 Creates an IlvBitmapData from a rectangular area in an IlvSystemPort. More...
 

Detailed Description

Port class.

Library: xviews or winviews or mviews (mutually exclusive)

Instances of the IlvBitmap class are rectangular areas that store a group of pixels that make an image. These images can be in full color. In this case, each pixel value represents a color index when your display system has no true-color capabilities. To find the exact color that will be displayed for this pixel, the system lookup table is consulted. If your display system has true color capabilities, then each pixel of the bitmap stores its complete color information.

Also, images can be monochrome. In this case, there is only one bit per pixel, and the drawing of these one-bit-deep bitmaps will take place by setting the 1 pixels to the foreground color of the palette that is used, and the 0 pixels will be set to the background color of this palette or left unchanged.

A colored bitmap can be associated a mask. A mask is a monochrome bitmap that indicates which of the pixels in the actual source image will be displayed. The pixels in the bitmap that correspond to '0' bits in the mask will be capable of not being displayed, achieving the effect of a transparent bitmap, that is, a color bitmap that has transparent parts.

Because IlvBitmap derives from IlvPort, you can actually draw into bitmap using the member functions of its parent classes. Most of the time, though, a bitmap is made from the conversion of a data file using an IlvBitmapStreamer.

See also
IlvBitmapData, IlvBitmapStreamer, IlvIcon, IlvTransparentIcon, IlvZoomableIcon, IlvZoomableTransparentIcon.

Member Enumeration Documentation

§ MemoryType

The different types of memory location used by bitmaps.

Note
This enumeration is used for the Windows port only.

Indicates the type of memory used by a given bitmap.

See also
getMemoryType(), IlvWindowsDisplayConfig::setBitmapAllocationFailedCallback(IlvBitmapAllocationFailedCallback).
Enumerator
NoMemory 

Bitmap storage is invalid.

VideoMemory 

Bitmap storage is allocated in the memory of the video card.

SystemMemory 

Bitmap storage is allocated in the system memory.

Constructor & Destructor Documentation

§ IlvBitmap() [1/3]

IlvBitmap::IlvBitmap ( IlvDisplay display,
IlvDim  width,
IlvDim  height,
IlUShort  depth,
unsigned char *  data,
IlBoolean  bitOrder = IlTrue,
IlUShort  padding = 32 
)

Constructor.

Initializes an empty image. Its content is unpredictable but the memory area to hold a future valid image is allocated and made available.

Parameters
displayThe display where this bitmap is created.
widthThe width of this new bitmap.
heightThe height of this new bitmap.
depthThe depth of this new bitmap, that is, how many bits should be used to hold the pixel value of each individual image element. This can be either 1 for monochrome bitmaps, or the depth of the display as returned by calling IlvDisplay::screenDepth().
dataThe initial data that initializes the bitmap pixel. This data must respect the following rules:
  • The whole image is given as a series of scan lines from image top to bottom.
  • The pixel values are packed into bytes from left to right, and each scan line must be padded to padding bits.
  • The bits are packed into padding bit words from left to right with a bit order defined by bitOrder.
  • The data may be composed in three different ways - either successive bytes or successive 32-bit integers - depending on the display depth:
    • If depth is 1, the data must be made of successive bytes, where each bit describes a pixel of the image.
    • If depth is greater than 1 but less than or equal to 8, the bitmap uses a lookup color table (also called color map) and each byte of data gives the index in this color map where the actual color value can be found.
    • If depth is strictly greater than 8, the data must be made of successive 32-bit integers in MSB format. In that case, each of the three color components consists of 8-bits. These three bytes must be packed into 32 bits in this way:
      value = (red << 16) | (green << 8) | blue
bitOrderIndicates the bit order of the data. The data bits are considered most significant bits first if bitOrder is IlTrue, or least significant bits first if bitOrder is set to IlFalse.
paddingThe padding value. The length of each scan line in data must be a multiple of this value.

§ IlvBitmap() [2/3]

IlvBitmap::IlvBitmap ( IlvDisplay display,
IlvDim  width,
IlvDim  height,
IlUShort  depth 
)

Constructor.

Initializes a bitmap that has the indicated size and depth. The initial contents are unpredictable.

Parameters
displayThe display where this bitmap is created.
widthThe width of this new bitmap.
heightThe height of this new bitmap.
depthThe depth of this new bitmap, that is, how many bits should be used to hold the pixel value of each individual image element. This can be either 1 for monochrome bitmaps, or the depth of the display as returned by calling display->screenDepth().

§ IlvBitmap() [3/3]

IlvBitmap::IlvBitmap ( IlvDisplay display,
IlvWindowsHandle  hBitmap,
IlBoolean  owner = IlFalse 
)

Constructor from an HBITMAP.

Initializes a bitmap from a Windows handle to a bitmap (HBITMAP). The width, height, and depth are retrieved directly from the HBITMAP.

Parameters
displayA pointer to an IlvDisplay.
hBitmapThe HBITMAP.
ownerA Boolean that indicates whether the object must delete the HBITMAP when this parameter is IlTrue or not delete it when this parameter is IlFalse.

Member Function Documentation

§ computeMask()

IlBoolean IlvBitmap::computeMask ( )

Computes the mask of this bitmap.

This member function computes a monochrome mask of the image currently stored in this bitmap. This mask is used to draw this bitmap transparently. The mask has the same dimensions as this bitmap, but every pixel of the original image that matches the transparent color index will be converted to a '0' bit in the output mask (see setTransparentColorIndex). All other pixels will result in a '1' in the mask. The original image may be modified after a call to computeMask.

Returns
IlTrue if the mask is successfully computed (that is, there is a transparent color index that was used to compute the image mask). If the original bitmap is monochrome, or if the transparent color index has not been set, then this member function returns IlFalse.

§ depth()

IlUShort IlvBitmap::depth ( ) const
virtual

Retrieves the depth of this bitmap.

Returns
The depth of the bitmap.

Reimplemented from IlvSystemPort.

§ getAnimationHandler()

IlvBitmapAnimationHandler* IlvBitmap::getAnimationHandler ( ) const

Returns the animation handler connected to this bitmap.

Returns
The animation handler connected to this bitmap, or 0 if there's none.
See also
IlvBitmapAnimationHandler, setAnimationHandler

§ getMask()

IlvBitmap* IlvBitmap::getMask ( ) const

Retrieves the mask of this bitmap.

Returns
The image mask bitmap, or 0 if there is none (that is, the bitmap has no transparent area).

§ getMemoryType()

MemoryType IlvBitmap::getMemoryType ( ) const

Gets the type of memory used in this bitmap.

Note
This enumeration is used for the Windows port only.

Views can allocate bitmaps in the video card memory or in the system memory, depending of the deployment environment state and the application configuration. This methods lets your application query the type of memory that is used for this bitmap.

Returns
The type of memory that this bitmap consumes.
See also
IlvWindowsDisplayConfig::setPreferredBitmapMemoryType(IlvBitmap::MemoryType).

§ getName()

const char* IlvBitmap::getName ( ) const
virtual

Retrieves the name of this bitmap.

Returns
The name of the bitmap object, if any was set.

Reimplemented from IlvValueInterface.

§ getTransparentColorIndex()

IlInt IlvBitmap::getTransparentColorIndex ( ) const

Retrieves the transparent color of this bitmap.

Returns
The index of the color that must be considered as transparent in the bitmap. This index will be used to compute the image mask when the bitmap is first requested to be displayed as transparent. It is automatically updated when creating the bitmap from a bitmap file that stores the transparent color information. A returned value of -1 means that this bitmap has no transparent color.

§ isABitmap()

virtual IlBoolean IlvBitmap::isABitmap ( ) const
virtual

Queries the nature of this port.

Returns
A Boolean value that is always IlTrue.

Reimplemented from IlvSystemPort.

§ lock()

void IlvBitmap::lock ( )
virtual

Locks the bitmap.

You must call this function if you want this bitmap to be shared among different objects (such as in the IlvIcon class).

Reimplemented from IlvValueInterface.

§ save() [1/2]

virtual IlBoolean IlvBitmap::save ( const char *  filename) const
virtual

Saves the bitmap to a file.

Writes out the binary description of the image.

Parameters
filenameThe filename of the file where this bitmap is saved.
Returns
IlTrue if the save is successful, and IlFalse otherwise.

§ save() [2/2]

virtual IlBoolean IlvBitmap::save ( ostream &  stream) const
virtual

Saves a bitmap to a stream.

Writes out the binary description of the image.

Parameters
streamThe output stream where this bitmap is saved.
Returns
IlTrue if the save is successful, and IlFalse otherwise.

§ saveAscii()

IlBoolean IlvBitmap::saveAscii ( const char *  filename) const

Saves an ASCII representation of this bitmap to a file.

The description of this IlvBitmap image will be stored in XBM (black and white) or XPM (color) format. This makes it easier, for example, to transfer your images from one site to another. The IlvDisplay class has a member function that lets you read from this new format (see IlvDisplay::readAsciiBitmap).

Parameters
filenameThe filename of the file where this bitmap is saved.
Returns
IlTrue if the save is successful, and IlFalse otherwise.

§ setAnimationHandler()

void IlvBitmap::setAnimationHandler ( IlvBitmapAnimationHandler handler)

Sets the animation handler connected to this bitmap.

The animation handler is deleted when the bitmap will be deleted.

Parameters
handlerThe animation handler.
See also
IlvBitmapAnimationHandler, getAnimationHandler

§ setMask()

void IlvBitmap::setMask ( IlvBitmap mask)

Sets the mask of this bitmap.

The previous mask is unlocked, and the new mask is locked.

Parameters
maskThe new mask of this bitmap.

§ setName()

void IlvBitmap::setName ( const char *  name)

Sets the name of this bitmap.

Parameters
nameThe string that is copied as the new name of this bitmap.

§ setTransparentColorIndex()

void IlvBitmap::setTransparentColorIndex ( IlInt  tcIndex)

Sets the transparent color of this bitmap.

Parameters
tcIndexThe new transparent color index of this bitmap.

§ unLock()

void IlvBitmap::unLock ( )
virtual

Unlocks the bitmap.

If no more objects are locking this bitmap, it will then be destroyed.

Reimplemented from IlvValueInterface.

§ useColor()

void IlvBitmap::useColor ( IlvColor color)

Verbose:

Indicates that the color referred to as color is used in this bitmap. The effect of this function call is that the color will be locked, and referenced to be unlocked when the bitmap is destroyed.

Parameters
colorThe color that this bitmap is indicated to use.

© Copyright 2018, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.