AgateLib.DisplayLib.Surface Class Reference

Class which represents a pixel surface. There are several ways to create a Surface object. The most common is to pass the name of an image file. More...

Inheritance diagram for AgateLib.DisplayLib.Surface:

List of all members.

Public Member Functions
	Surface (Resources.AgateResourceCollection resources, string name)
	Creates a surface object from a resource.
	Surface (string filename)
	Creates a surface object, from the specified image file.
	Surface (IFileProvider fileProvider, string filename)
	Creates a surface object using the specified file provider to open the image file.
	Surface (Stream st)
	Creates a surface object from the data in the specified stream.
	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 (Vector2 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 (float x, float y, Rectangle srcRect, 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	DrawRects (RectangleF[] srcRects, RectangleF[] 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	DrawRects (Rectangle[] srcRects, Rectangle[] destRects, int start, int length)
	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	DrawRects (RectangleF[] srcRects, RectangleF[] destRects, int start, int length)
	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.
void	WritePixels (PixelBuffer buffer, Rectangle sourceRect, Point destPt)
	Copies the data directly from the PixelBuffer to the surface, overwriting a portion of the surface's pixel data. The selected source rectangle from the pixel buffer 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.
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.
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. Setting this is equivalent to setting the ColorGradient property with a gradient with the same color in all corners. If a gradient is being used, getting this property returns the top-left color in the gradient.
Gradient	ColorGradient [get, set]
	Gets or sets the gradient for this surface.
InterpolationMode	InterpolationHint [get, set]
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

Class which represents a pixel surface. There are several ways to create a Surface object. The most common is to pass the name of an image file.

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:

                Surface surface = new Surface("myimage.png");

VB Example to create a new surface from an image file:

                Dim surf as New Surface("myimage.png")

C# Example to draw surface to screen.

                surface.Draw(20, 20);

VB Example to draw surface to screen.

                surf.Draw(20, 20)

---

Constructor & Destructor Documentation

AgateLib.DisplayLib.Surface.Surface	(	Resources.AgateResourceCollection	resources,
		string	name
	)

Creates a surface object from a resource.

Parameters:

	resources
	name

AgateLib.DisplayLib.Surface.Surface

(

string

filename

)

Creates a surface object, from the specified image file.

Parameters:

filename

AgateLib.DisplayLib.Surface.Surface	(	IFileProvider	fileProvider,
		string	filename
	)

Creates a surface object using the specified file provider to open the image file.

Parameters:

	filename
	fileProvider

AgateLib.DisplayLib.Surface.Surface

(

Stream

st

)

Creates a surface object from the data in the specified stream.

Parameters:

st

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

Creates a surface object of the specified size.

Parameters:

	width
	height

AgateLib.DisplayLib.Surface.Surface

(

Size

size

)

Creates a surface object of the specified size.

Parameters:

size

AgateLib.DisplayLib.Surface.Surface

(

PixelBuffer

pixels

)

Constructs a surface object from the specified PixelBuffer object.

Parameters:

pixels

---

Member Function Documentation

Surface AgateLib.DisplayLib.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.

void AgateLib.DisplayLib.Surface.Dispose

(

)

Destroyes unmanaged resources associated with this surface.

void AgateLib.DisplayLib.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 AgateLib.DisplayLib.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 AgateLib.DisplayLib.Surface.Draw	(	float	x,
		float	y,
		Rectangle	srcRect,
		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 AgateLib.DisplayLib.Surface.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 AgateLib.DisplayLib.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 AgateLib.DisplayLib.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

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.Surface.Draw

(

Vector2

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 AgateLib.DisplayLib.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

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.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

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.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

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.Surface.Draw

(

)

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

void AgateLib.DisplayLib.Surface.DrawRects	(	RectangleF[]	srcRects,
		RectangleF[]	destRects,
		int	start,
		int	length
	)

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
	start	Element in the arrays to start at.
	length	Number of elements in the arrays to use.

void AgateLib.DisplayLib.Surface.DrawRects	(	Rectangle[]	srcRects,
		Rectangle[]	destRects,
		int	start,
		int	length
	)

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
	start	Element in the arrays to start at.
	length	Number of elements in the arrays to use.

void AgateLib.DisplayLib.Surface.DrawRects	(	RectangleF[]	srcRects,
		RectangleF[]	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 AgateLib.DisplayLib.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

static ImageFileFormat AgateLib.DisplayLib.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:

void AgateLib.DisplayLib.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

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.Surface.IncrementRotationAngle

(

double

radians

)

Increments the rotation angle of this surface.

Parameters:

radians

Value in radians to increase the rotation by.

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.Surface.IncrementRotationAngleDegrees

(

double

degrees

)

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

Parameters:

degrees

Implements AgateLib.DisplayLib.ISurface.

PixelBuffer AgateLib.DisplayLib.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:

PixelBuffer AgateLib.DisplayLib.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 AgateLib.DisplayLib.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:

void AgateLib.DisplayLib.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

void AgateLib.DisplayLib.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 AgateLib.DisplayLib.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

Implements AgateLib.DisplayLib.ISurface.

void AgateLib.DisplayLib.Surface.WritePixels	(	PixelBuffer	buffer,
		Rectangle	sourceRect,
		Point	destPt
	)

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

Parameters:

	buffer
	sourceRect
	destPt

void AgateLib.DisplayLib.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

void AgateLib.DisplayLib.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.

---

Property Documentation

double AgateLib.DisplayLib.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.

Implements AgateLib.DisplayLib.ISurface.

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

Gets or sets the multiplicative color for this surface. Setting this is equivalent to setting the ColorGradient property with a gradient with the same color in all corners. If a gradient is being used, getting this property returns the top-left color in the gradient.

Implements AgateLib.DisplayLib.ISurface.

Gradient AgateLib.DisplayLib.Surface.ColorGradient [get, set]

Gets or sets the gradient for this surface.

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

SurfaceImpl AgateLib.DisplayLib.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 AgateLib.DisplayLib.IRenderTarget.

bool AgateLib.DisplayLib.Surface.IsDisposed [get]

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

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

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

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

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

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

Implements AgateLib.DisplayLib.ISurface.

double AgateLib.DisplayLib.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).

Implements AgateLib.DisplayLib.ISurface.

bool AgateLib.DisplayLib.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 AgateLib.DisplayLib.Surface.SurfaceHeight [get]

Gets the height of the source surface in pixels.

Implements AgateLib.DisplayLib.ISurface.

Size AgateLib.DisplayLib.Surface.SurfaceSize [get]

Gets the Size of the source surface in pixels.

Implements AgateLib.DisplayLib.ISurface.

int AgateLib.DisplayLib.Surface.SurfaceWidth [get]

Gets the width of the source surface in pixels.

Implements AgateLib.DisplayLib.ISurface.

int AgateLib.DisplayLib.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.

Changing this value while using gradients can result in ugly transitions between different tesselation values. The reason is AgateLib will interpolate the gradient color to the vertices used, and then this is capped to integer values. So avoid doing this.

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².

---

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

• DisplayLib/Surface.cs