AgateLib: ERY.AgateLib.Surface Class Reference

List of all members.


Public Member Functions
	Surface (string filename)
	Creates a surface object, from the specified image file.
	Surface (int width, int height)
	Creates a surface object of the specified size.
	Surface (Size size)
	Creates a surface object of the specified size.
	Surface (PixelBuffer pixels)
	Constructs a surface object from the specified PixelBuffer object.
void	Dispose ()
	Destroyes unmanaged resources associated with this surface.
void	SetScale (double width, double height)
	Sets the amount of scaling when this surface is drawn. 1.0 is no scaling. Scale values can be negative, this causes the surface to be mirrored in that direction. This does not affect how the surface is aligned; eg. if DisplayAlignment is top-left and ScaleWidth < 0, the surface will still be drawn to the right of the point supplied to Draw(Point).
void	GetScale (out double width, out double height)
	Gets the amount of scaling when this surface is drawn. 1.0 is no scaling. Scale values can be negative, this causes the surface to be mirrored in that direction. This does not affect how the surface is aligned; eg. if DisplayAlignment is top-left and ScaleWidth < 0, the surface will still be drawn to the right of the point supplied to Draw(Point).
void	IncrementRotationAngle (double radians)
	Increments the rotation angle of this surface.
void	IncrementRotationAngleDegrees (double degrees)
	Increments the rotation angle of this surface. Value supplied is in degrees.
void	Draw ()
	Draws the surface to the top-left corner (0, 0) of the target.
void	Draw (int destX, int destY)
	Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.
void	Draw (float destX, float destY)
	Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.
void	Draw (Point destPt)
	Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.
void	Draw (PointF destPt)
	Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.
void	Draw (PointF destPt, PointF rotationCenter)
	Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface. Ignores the value of RotationCenter and uses the specified point to rotate around instead.
void	Draw (float destX, float destY, float rotationCenterX, float rotationCenterY)
	Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface. Ignores the value of RotationCenter and uses the specified point to rotate around instead.
void	Draw (Rectangle srcRect, Rectangle destRect)
	Draws a portion of this surface to the specified destination rectangle.
void	Draw (Rectangle destRect)
	Draws this surface to the specified destination rectangle.
void	DrawRects (Rectangle[] srcRects, Rectangle[] destRects)
	Draws the surface using an array of source and destination rectangles. This method will throw an exception if the two arrays are not the same size.
void	SaveTo (string filename)
	Saves the surface to the specified file.
void	SaveTo (string filename, ImageFileFormat format)
	Saves the surface to the specified file, with the specified file format. If the file has an extension such as ".png" or ".bmp" than the SaveTo(string) overload is prefered, as it chooses a file format which is consistent with the extension.
Surface	CarveSubSurface (Rectangle srcRect)
	Copies the pixels in this surface from the given source rectangle to a new surface, and returns that. It is not recommended to call this between calls to Display.BeginFrame..Display.EndFrame.
PixelBuffer	ReadPixels ()
	Returns a pixel buffer which contains a copy of the pixel data in the surface. The format of the pixel data is the same as of the raw data in the surface.
PixelBuffer	ReadPixels (PixelFormat format)
	Returns a pixel buffer which contains a copy of the pixel data in the surface.
PixelBuffer	ReadPixels (PixelFormat format, Rectangle rect)
	Returns a pixel buffer which contains a copy of the pixel data in the surface, inside the rectangle requested.
void	WritePixels (PixelBuffer buffer)
	Copies the data directly from PixelBuffer. The PixelBuffer must be the same width and height as the Surface's SurfaceWidth and SurfaceHeight.
void	WritePixels (PixelBuffer buffer, Point startPoint)
	Copies the data directly from PixelBuffer, overwriting a portion of the surface's pixel data. The PixelBuffer must fit within the surface.
Static Public Member Functions
static ImageFileFormat	FormatFromExtension (string filename)
	Returns a value in the ImageFileFormat enum based on the file extension of the given filename. No checks are done to see if that file exists.
Public Attributes
[Obsolete("Use ReadPixels and PixelBuffer.Is*Blank methods instead.")] boo	IsSurfaceBlank )()
	Checks to see whether the surface pixels all have alpha value less than the given value.
[Obsolete("Use ReadPixels and PixelBuffer.Is*Blank methods instead.")] boo	IsRowBlank )(int row)
	Checks to see whether all the pixels along the given row are all transparent, within the threshold.
[Obsolete("Use ReadPixels and PixelBuffer.Is*Blank methods instead.")] boo	IsColumnBlank )(int col)
	Checks to see whether all the pixels along the given column are all transparent, within the threshold.
Properties
bool	IsDisposed `[get]`
	Returns true if Dispose() has been called on this surface.
int	TesselateFactor `[get, set]`
	Gets or sets how many times this surface should be broken down when drawn. A TesselateFactor of 2 indicates that each time this surface is drawn, it's drawn in 4 (2x2) chunks.
bool	ShouldBePacked `[get, set]`
	Gets or sets a bool value that indicates whether or not this surface should be included in a call to Display.PackAllSurfaces.
int	SurfaceWidth `[get]`
	Gets the width of the source surface in pixels.
int	SurfaceHeight `[get]`
	Gets the height of the source surface in pixels.
Size	SurfaceSize `[get]`
	Gets the Size of the source surface in pixels.
int	DisplayWidth `[get, set]`
	Get or sets the width of the surface in pixels when it will be displayed on screen.
int	DisplayHeight `[get, set]`
	Gets or sets the height of the surface in pixels when it is displayed on screen.
Size	DisplaySize `[get, set]`
	Gets or sets the Size of the area used by this surface when displayed on screen.
virtual double	Alpha `[get, set]`
	Alpha value for displaying this surface. Valid values range from 0.0 (completely transparent) to 1.0 (completely opaque). Internally stored as a byte, so granularity is only 1/255.0.
double	RotationAngle `[get, set]`
	Gets or sets the rotation angle in radians. Positive angles indicate rotation in the Counter-Clockwise direction.
double	RotationAngleDegrees `[get, set]`
	Gets or sets the rotation angle in degrees. Positive angles indicate rotation in the Counter-Clockwise direction.
OriginAlignment	RotationCenter `[get, set]`
	Gets or sets the point on the surface which is used to rotate around.
OriginAlignment	DisplayAlignment `[get, set]`
	Gets or sets the point where the surface is aligned to when drawn.
double	ScaleWidth `[get, set]`
	Gets or sets the amount the width is scaled when this surface is drawn. 1.0 is no scaling. Scale values can be negative, this causes the surface to be mirrored in that direction. This does not affect how the surface is aligned; eg. if DisplayAlignment is top-left and ScaleWidth < 0, the surface will still be drawn to the right of the point supplied to Draw(Point).
double	ScaleHeight `[get, set]`
	Gets or sets the amount the height is scaled when this surface is drawn. 1.0 is no scaling.
Color	Color `[get, set]`
	Gets or sets the multiplicative color for this surface. Remember, Color structures have an alpha field, so setting this will override any value set by Alpha. If you want to set Alpha separately, set the Alpha property after the SurfaceColor property.
SurfaceImpl	Impl `[get]`
	Gets the object which does actual rendering of this surface. This may be cast to a surface object in whatever rendering library is being used (eg. if using the MDX_1_1 library, this can be cast to an MDX1_Surface object). You only need to use this if you want to access features which are specific to the graphics library you're using.

Detailed Description

Using a surface to draw on the screen is very simple. There are several overloaded Draw methods which do that.

You must have created a DisplayWindow object before creating any Surface objects. C# Example to create a new surface from an image file:

Constructor & Destructor Documentation

ERY.AgateLib.Surface.Surface ( string filename )

Creates a surface object, from the specified image file.

Parameters:

filename

ERY.AgateLib.Surface.Surface	(	int	width,
		int	height
	)

Creates a surface object of the specified size.

Parameters:

	width
	height

ERY.AgateLib.Surface.Surface ( Size size )

Creates a surface object of the specified size.

Parameters:

size

ERY.AgateLib.Surface.Surface ( PixelBuffer pixels )

Constructs a surface object from the specified PixelBuffer object.

Parameters:

pixels

Member Function Documentation

void ERY.AgateLib.Surface.Dispose ( )

Destroyes unmanaged resources associated with this surface.

void ERY.AgateLib.Surface.SetScale	(	double	width,
		double	height
	)

Sets the amount of scaling when this surface is drawn. 1.0 is no scaling. Scale values can be negative, this causes the surface to be mirrored in that direction. This does not affect how the surface is aligned; eg. if DisplayAlignment is top-left and ScaleWidth < 0, the surface will still be drawn to the right of the point supplied to Draw(Point).

Parameters:

	width
	height

void ERY.AgateLib.Surface.GetScale	(	out double	width,
		out double	height
	)

Gets the amount of scaling when this surface is drawn. 1.0 is no scaling. Scale values can be negative, this causes the surface to be mirrored in that direction. This does not affect how the surface is aligned; eg. if DisplayAlignment is top-left and ScaleWidth < 0, the surface will still be drawn to the right of the point supplied to Draw(Point).

Parameters:

	width
	height

void ERY.AgateLib.Surface.IncrementRotationAngle ( double radians )

Increments the rotation angle of this surface.

Parameters:

radians

Value in radians to increase the rotation by.

void ERY.AgateLib.Surface.IncrementRotationAngleDegrees ( double degrees )

Increments the rotation angle of this surface. Value supplied is in degrees.

Parameters:

degrees

void ERY.AgateLib.Surface.Draw ( )

Draws the surface to the top-left corner (0, 0) of the target.

void ERY.AgateLib.Surface.Draw	(	int	destX,
		int	destY
	)

Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.

Parameters:

	destX
	destY

void ERY.AgateLib.Surface.Draw	(	float	destX,
		float	destY
	)

Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.

Parameters:

	destX
	destY

void ERY.AgateLib.Surface.Draw ( Point destPt )

Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.

Parameters:

destPt

void ERY.AgateLib.Surface.Draw ( PointF destPt )

Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface.

Parameters:

destPt

void ERY.AgateLib.Surface.Draw	(	PointF	destPt,
		PointF	rotationCenter
	)

Draws this surface to the screen at the specified point, using all the state information defined in the properties of this surface. Ignores the value of RotationCenter and uses the specified point to rotate around instead.

Parameters:

	destPt
	rotationCenter	Center of rotation to use, relative to the top-left of the surface.

void ERY.AgateLib.Surface.Draw	(	float	destX,
		float	destY,
		float	rotationCenterX,
		float	rotationCenterY
	)

void ERY.AgateLib.Surface.Draw	(	Rectangle	srcRect,
		Rectangle	destRect
	)

Draws a portion of this surface to the specified destination rectangle.

State settings which are ignored are RotationAngle, DisplayAlignment and Scaling. Color and alpha values are still used.

Parameters:

	srcRect
	destRect

void ERY.AgateLib.Surface.Draw ( Rectangle destRect )

Draws this surface to the specified destination rectangle.

State settings which are ignored are RotationAngle, DisplayAlignment and Scaling. Color and alpha values are still used.

Parameters:

destRect

void ERY.AgateLib.Surface.DrawRects	(	Rectangle[]	srcRects,
		Rectangle[]	destRects
	)

Draws the surface using an array of source and destination rectangles. This method will throw an exception if the two arrays are not the same size.

Parameters:

	srcRects
	destRects

void ERY.AgateLib.Surface.SaveTo ( string filename )

Saves the surface to the specified file.

Infers the file format from the extension. If there is no extension present or it is unrecognized, PNG is assumed.

Parameters:

filename

void ERY.AgateLib.Surface.SaveTo	(	string	filename,
		ImageFileFormat	format
	)

Saves the surface to the specified file, with the specified file format. If the file has an extension such as ".png" or ".bmp" than the SaveTo(string) overload is prefered, as it chooses a file format which is consistent with the extension.

Parameters:

	filename
	format

Surface ERY.AgateLib.Surface.CarveSubSurface ( Rectangle srcRect )

Copies the pixels in this surface from the given source rectangle to a new surface, and returns that. It is not recommended to call this between calls to Display.BeginFrame..Display.EndFrame.

Parameters:

srcRect

The rectangle of pixels to create a new surface from.

Returns:: A Surface object containing only those pixels copied.

PixelBuffer ERY.AgateLib.Surface.ReadPixels ( )

Returns a pixel buffer which contains a copy of the pixel data in the surface. The format of the pixel data is the same as of the raw data in the surface.

Returns:

PixelBuffer ERY.AgateLib.Surface.ReadPixels ( PixelFormat format )

Returns a pixel buffer which contains a copy of the pixel data in the surface.

Parameters:

format

Format of the pixel data wanted. Automatic conversion is performed, if necessary. Use PixelFormat.Any to retrieve data in its original format, without conversion.

Returns:

PixelBuffer ERY.AgateLib.Surface.ReadPixels	(	PixelFormat	format,
		Rectangle	rect
	)

Returns a pixel buffer which contains a copy of the pixel data in the surface, inside the rectangle requested.

Parameters:

	format	Format of the pixel data wanted. Automatic conversion is performed, if necessary. Use PixelFormat.Any to retrieve data in its original format, without conversion.
	rect	Area of the Surface from which to retrieve data.

Returns:

void ERY.AgateLib.Surface.WritePixels ( PixelBuffer buffer )

Copies the data directly from PixelBuffer. The PixelBuffer must be the same width and height as the Surface's SurfaceWidth and SurfaceHeight.

Parameters:

buffer

The PixelBuffer which contains pixel data to copy from.

void ERY.AgateLib.Surface.WritePixels	(	PixelBuffer	buffer,
		Point	startPoint
	)

Copies the data directly from PixelBuffer, overwriting a portion of the surface's pixel data. The PixelBuffer must fit within the surface.

Parameters:

	buffer	The PixelBuffer which contains pixel data to copy from.
	startPoint

static ImageFileFormat ERY.AgateLib.Surface.FormatFromExtension ( string filename ) [static]

Returns a value in the ImageFileFormat enum based on the file extension of the given filename. No checks are done to see if that file exists.

Parameters:

filename

Returns:

Member Data Documentation

[Obsolete("Use ReadPixels and PixelBuffer.Is*Blank methods instead.")] boo ERY.AgateLib.Surface.IsSurfaceBlank)(int alphaThreshold)

Checks to see whether the surface pixels all have alpha value less than the given value.

Returns:

[Obsolete("Use ReadPixels and PixelBuffer.Is*Blank methods instead.")] boo ERY.AgateLib.Surface.IsRowBlank)(int row)

Checks to see whether all the pixels along the given row are all transparent, within the threshold.

Parameters:

row

Which row. Valid range is between 0 and SurfaceSize.Height - 1.

Returns:

[Obsolete("Use ReadPixels and PixelBuffer.Is*Blank methods instead.")] boo ERY.AgateLib.Surface.IsColumnBlank)(int col)

Checks to see whether all the pixels along the given column are all transparent, within the threshold.

Parameters:

col

Which column. Valid range is between 0 and SurfaceSize.Width - 1.

Returns:

Property Documentation

bool ERY.AgateLib.Surface.IsDisposed [get]

Returns true if Dispose() has been called on this surface.

int ERY.AgateLib.Surface.TesselateFactor [get, set]

Gets or sets how many times this surface should be broken down when drawn. A TesselateFactor of 2 indicates that each time this surface is drawn, it's drawn in 4 (2x2) chunks.

This property is used to divide a surface drawn up into smaller surfaces which are drawn independently. The reason to do this is lighting calculations (without using shaders) are done on a per-vertex basis. When a light source is close to a large surface, this will create noticably bad lighting, because only the lighting properties at the corners are calculated, and then the lighting is interpolated between the end points.

Setting this value high may have a significant impact on performance. For each time a Surface.Draw() overload is called, the number of triangles which are calculated and sent to the rasterizer is 2 * TesselateFactor².

bool ERY.AgateLib.Surface.ShouldBePacked [get, set]

Gets or sets a bool value that indicates whether or not this surface should be included in a call to Display.PackAllSurfaces.

int ERY.AgateLib.Surface.SurfaceWidth [get]

Gets the width of the source surface in pixels.

int ERY.AgateLib.Surface.SurfaceHeight [get]

Gets the height of the source surface in pixels.

Size ERY.AgateLib.Surface.SurfaceSize [get]

Gets the Size of the source surface in pixels.

int ERY.AgateLib.Surface.DisplayWidth [get, set]

Get or sets the width of the surface in pixels when it will be displayed on screen.

int ERY.AgateLib.Surface.DisplayHeight [get, set]

Gets or sets the height of the surface in pixels when it is displayed on screen.

Size ERY.AgateLib.Surface.DisplaySize [get, set]

Gets or sets the Size of the area used by this surface when displayed on screen.

virtual double ERY.AgateLib.Surface.Alpha [get, set]

Alpha value for displaying this surface. Valid values range from 0.0 (completely transparent) to 1.0 (completely opaque). Internally stored as a byte, so granularity is only 1/255.0.

double ERY.AgateLib.Surface.RotationAngle [get, set]

Gets or sets the rotation angle in radians. Positive angles indicate rotation in the Counter-Clockwise direction.

double ERY.AgateLib.Surface.RotationAngleDegrees [get, set]

Gets or sets the rotation angle in degrees. Positive angles indicate rotation in the Counter-Clockwise direction.

OriginAlignment ERY.AgateLib.Surface.RotationCenter [get, set]

Gets or sets the point on the surface which is used to rotate around.

OriginAlignment ERY.AgateLib.Surface.DisplayAlignment [get, set]

Gets or sets the point where the surface is aligned to when drawn.

double ERY.AgateLib.Surface.ScaleWidth [get, set]

Gets or sets the amount the width is scaled when this surface is drawn. 1.0 is no scaling. Scale values can be negative, this causes the surface to be mirrored in that direction. This does not affect how the surface is aligned; eg. if DisplayAlignment is top-left and ScaleWidth < 0, the surface will still be drawn to the right of the point supplied to Draw(Point).

double ERY.AgateLib.Surface.ScaleHeight [get, set]

Gets or sets the amount the height is scaled when this surface is drawn. 1.0 is no scaling.

Color ERY.AgateLib.Surface.Color [get, set]

Gets or sets the multiplicative color for this surface. Remember, Color structures have an alpha field, so setting this will override any value set by Alpha. If you want to set Alpha separately, set the Alpha property after the SurfaceColor property.

SurfaceImpl ERY.AgateLib.Surface.Impl [get]

Gets the object which does actual rendering of this surface. This may be cast to a surface object in whatever rendering library is being used (eg. if using the MDX_1_1 library, this can be cast to an MDX1_Surface object). You only need to use this if you want to access features which are specific to the graphics library you're using.

Implements ERY.AgateLib.IRenderTarget.

ERY.AgateLib.Surface Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Properties

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

Property Documentation