Namespace List Class Hierarchy Compound List File List Namespace Members Compound Members

# ptc::BaseSurface Class Reference

Surface interface. More...

Class diagram for ptc::BaseSurface:

List of all members.

## Public Members

- virtual ~BaseSurface ()
- virtual void copy (BaseSurface &surface) = 0
- virtual void copy (BaseSurface &surface,const Area &source,const Area &destination) = 0
- virtual void* lock () = 0
- virtual void unlock () = 0
- virtual void load (const void *pixels,int width,int height,int pitch,const Format &format,const Palette &palette) = 0
- virtual void load (const void *pixels,int width,int height,int pitch,const Format &format,const Palette &palette,const Area &source,const Area &destination) = 0
- virtual void save (void *pixels,int width,int height,int pitch,const Format &format,const Palette &palette) = 0
- virtual void save (void *pixels,int width,int height,int pitch,const Format &format,const Palette &palette,const Area &source,const Area &destination) = 0
- virtual void clear () = 0
- virtual void clear (const Color &color) = 0
- virtual void clear (const Color &color,const Area &area) = 0
- virtual void palette (const Palette &palette) = 0
- virtual const Palette& palette () const = 0
- virtual void clip (const Area &area)
- virtual int width () const = 0
- virtual int height () const = 0
- virtual int pitch () const = 0
- virtual const Area& area () const = 0
- virtual const Area& clip () const = 0
- virtual const Format& format () const = 0
- virtual bool option (const char option[]) = 0

## Detailed Description

Surface interface.

This class provides the interface for manipulating an array of pixels.

The ptc::Surface and ptc::Console classes are concrete implementations of this interface.

## Member Function Documentation

### virtual ptc::BaseSurface::~BaseSurface ()`[virtual]`

Virtual destructor.

### virtual void ptc::BaseSurface::copy (BaseSurface & surface)`[pure virtual]`

Copies the entire contents of this surface to the other surface specified in the surface parameter.

Parameters:
  surface - the destination surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::copy (BaseSurface & surface, const Area & source, const Area & destination)`[pure virtual]`

Copies an area of this surface to an area of the other surface specified in the surface parameter.

The source and destination areas are clipped to the clip areas of both surfaces.

Parameters:
  surface - the destination surface.
  source - the source area.
  destination - the destination area.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void * ptc::BaseSurface::lock ()`[pure virtual]`

Locks the surface and returns a pointer to the locked surface pixel memory.

Every successful lock must be followed by a call to BaseSurface::unlock(). Call unlock once you are finished with the surface memory.

Only one lock per surface object is permitted at any one time.

If the surface is already locked a ptc::Error exception will be thrown.

Returns:
  A pointer to the surface pixel memory.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::unlock ()`[pure virtual]`

Unlocks the surface memory after it was locked by a call to BaseSurface::lock().

The pointer to the pixel memory retrieved during lock becomes invalid upon return from this function. If you need to access pixel memory again, you must lock the surface again with BaseSurface::lock().

If the surface was not locked then a ptc::Error exception will be thrown.

Returns:
  A pointer to the surface pixel memory.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::load (const void * pixels, int width, int height, int pitch, const Format & format, const Palette & palette)`[pure virtual]`

Loads pixels from the pixel array pixels to the surface.

Parameters:
  pixels - the pixel data to be loaded.
  width - the width of the pixel data in pixels.
  height - the height of the pixel data in pixels.
  pitch - the pitch of the pixel data in bytes.
  format - the format of the pixel data.
  palette - the palette of the pixel data (ignored in direct color).

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::load (const void * pixels, int width, int height, int pitch, const Format & format, const Palette & palette, const Area & source, const Area & destination)`[pure virtual]`

Loads an area of pixels from the pixel array pixels to an area of the surface.

The source and destination areas are clipped to the surface clip area and the dimensions of the pixel data.

Parameters:
  pixels - the pixel data to be loaded.
  width - the width of the pixel data in pixels.
  height - the height of the pixel data in pixels.
  pitch - the pitch of the pixel data in bytes.
  format - the format of the pixel data.
  palette - the palette of the pixel data (ignored in direct color).
  source - the source area of pixels to be loaded.
  destination - the destination area where pixels will be loaded on the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::save (void * pixels, int width, int height, int pitch, const Format & format, const Palette & palette)`[pure virtual]`

Saves the surface pixels to the pixel array pixels.

Parameters:
  pixels - the destination pixel data.
  width - the width of the pixel data in pixels.
  height - the height of the pixel data in pixels.
  pitch - the pitch of the pixel data in bytes.
  format - the format of the pixel data.
  palette - the palette of the pixel data (ignored in direct color).

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::save (void * pixels, int width, int height, int pitch, const Format & format, const Palette & palette, const Area & source, const Area & destination)`[pure virtual]`

Saves an area of the surface pixels to an area of the pixel data array pixels.

The source and destination areas are clipped to the surface clip area and the dimensions of the pixel data.

Parameters:
  pixels - the destination pixel data.
  width - the width of the pixel data in pixels.
  height - the height of the pixel data in pixels.
  pitch - the pitch of the pixel data in bytes.
  format - the format of the pixel data.
  palette - the palette of the pixel data (ignored in direct color).
  source - the source area of pixels to be saved.
  destination - the destination area where pixels will be saved to the pixel data array.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::clear ()`[pure virtual]`

Clears the entire contents of the surface to black in direct color and index zero in indexed color.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::clear (const Color & color)`[pure virtual]`

Clears the entire contents of the surface to the color specified in the color parameter.

If the surface pixels are direct color format then the color parameter must specify a direct color r,g,b,a value.

Conversely, if the surface pixels are indexed color then the color parameter must specify a color index value.

Parameters:
  color - the clear color.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::clear (const Color & color, const Area & area)`[pure virtual]`

Clears the area of pixels of the surface specified by the area parameter to the color specified in the color parameter.

If the surface pixels are direct color format then the color parameter must specify a direct color r,g,b,a value.

Conversely if the surface pixels are indexed color then the color parameter must specify a color index value.

The clear area is clipped to the surface clip area.

Parameters:
  color - the clear color.
  area - the clear area.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::palette (const Palette & palette)`[pure virtual]`

Sets the surface palette to the palette specified in the palette parameter.

Setting the surface palette in direct color will not cause an error to be thrown even though it has no effect.

Parameters:
  palette - the palette data.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual const Palette & ptc::BaseSurface::palette () const`[pure virtual]`

Gets the surface palette object.

Returns:
  The surface palette object.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual void ptc::BaseSurface::clip (const Area & area)`[virtual]`

Sets the surface clip area to the area specified by the area parameter.

Before the clip area is set it is clipped against the surface area (0,0,width,height).

This ensures that the clip area is always contained within the boundaries of the surface.

See also:
  BaseSurface::clip()

Parameters:
  area - the clip area.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual int ptc::BaseSurface::width () const`[pure virtual]`

Gets the width of the surface in pixels.

Returns:
  The width of the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual int ptc::BaseSurface::height () const`[pure virtual]`

Gets the height of the surface in pixels.

Returns:
  The height of the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual int ptc::BaseSurface::pitch () const`[pure virtual]`

Gets the pitch of the surface in bytes.

The pitch is the number of bytes between the start of each horizonal line of pixel memory.

The pitch may be any value - even negative!

Do not make any assumptions about the layout of BaseSurface pixel memory, always check the pitch!

Returns:
  The pitch of the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual const Area & ptc::BaseSurface::area () const`[pure virtual]`

Gets the area of the surface.

The surface area is calculated as Area( 0, 0, surface.width(), surface.height() ).

Returns:
  The area of the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual const Area & ptc::BaseSurface::clip () const`[pure virtual]`

Gets the clip area of the surface.

The surface clip area is used during clipping areas to the surface.

The clip area is initially set to (0,0,width,height) but may be changed with BaseSurface::clip(const Area &area).

Returns:
  The area of the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual const Format & ptc::BaseSurface::format () const`[pure virtual]`

Gets the pixel format of the surface.

Returns:
  The pixel format of the surface.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

### virtual bool ptc::BaseSurface::option (const char option[])`[pure virtual]`

Passes an implementation specific option string to the surface.

Returns:
  true if the option string is recognized, false otherwise.

Exceptions:
  Error - An Error exception is thrown on failure.

Reimplemented in ptc::Surface, and ptc::Console.

The documentation for this class was generated from the following file:

- ptc.h