#region LGPL License
/*************************************************************************
Crazy Eddie's GUI System (http://crayzedsgui.sourceforge.net)
Copyright (C)2004 Paul D Turner (crayzed@users.sourceforge.net)
C# Port developed by Chris McGuirk (leedgitar@latenitegames.com)
Compatible with the Axiom 3D Engine (http://axiomengine.sf.net)
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*************************************************************************/
#endregion LGPL License
#region Using directives
using System;
using System.Text;
#endregion
namespace CrayzEdsGui.Base{
/// <summary>
/// Abstract class defining the interface for Renderer objects.
/// </summary>
/// <remarks>
/// Objects derived from Renderer are the means by which the GUI system interfaces
/// with specific rendering technologies. To use a rendering system or API to draw
/// CEGUI imagery requires that an appropriate Renderer object be available.
/// </remarks>
public abstract class Renderer {
#region Constants
/// <summary>
/// Initial value to use for 'z' each frame.
/// </summary>
const float GuiZInitialValue = 1.0f;
/// <summary>
/// Value to step 'z' for each GUI element.
/// </summary>
/// <remarks>
/// Enough for 1000 windows.
/// </remarks>
const float GuiZElementStep = 0.001f;
/// <summary>
/// Value to step 'z' for each GUI layer.
/// </summary>
/// <remarks>
/// Enough for 10 layers per window.
/// </remarks>
const float GuiZLayerStep = 0.0001f;
#endregion Constants
#region Fields
/// <summary>
/// The current z co-ordinate value.
/// </summary>
protected float currentZ;
/// <summary>
/// If false, each call to <see cref="AddQuad"/> will be rendered immediately.
/// If true, calls will be queued and issued in a batch during a <see cref="DoRender"/> call.
/// </summary>
protected bool isQueueingEnabled;
#endregion Fields
#region Events / Event Methods
#region DisplayModeChanged
/// <summary>
/// Fires when the underlying display mode had changed.
/// </summary>
/// <remarks>
/// It is important that all Renderer implementers fire this properly as the
/// system itself subscribes to this event.
/// </remarks>
public event GuiEventHandler DisplayModeChanged;
/// <summary>
/// Internal method for firing the <see cref="DisplayModeChanged"/> event.
/// </summary>
/// <param name="e">Event arguments.</param>
protected void OnDisplayModeChanged(GuiEventArgs e) {
if (DisplayModeChanged != null) {
DisplayModeChanged(this, e);
}
}
#endregion DisplayModeChanged
#endregion Events / Event Methods
#region Constructor
/// <summary>
/// Default constructor.
/// </summary>
protected Renderer() {
// intialize Z by default
ResetZValue();
}
#endregion Constructor
#region Abstract Members
#region Properties
/// <summary>
/// Return the current height of the display in pixels.
/// </summary>
/// <value>Float value equal to the current height of the display in pixels.</value>
public abstract float Height { get; }
/// <summary>
/// Return the horizontal display resolution dpi.
/// </summary>
/// <value>Horizontal resolution of the display in dpi.</value>
public abstract int HorizontalScreenDPI { get; }
/// <summary>
/// Return the maximum texture size available.
/// </summary>
/// <value>Size of the maximum supported texture in pixels (textures are always assumed to be square).</value>
public abstract int MaxTextureSize { get; }
/// <summary>
/// Return a <see cref="Rect"/> describing the screen.
/// </summary>
/// <value>
/// A Rect object that describes the screen area. Typically, the top-left values are always 0,
/// and the size of the area described is equal to the screen resolution.
/// </value>
public abstract Rect Rect { get; }
/// <summary>
/// Return the size of the display in pixels.
/// </summary>
/// <value>Size object describing the dimensions of the current display.</value>
public abstract Size Size { get; }
/// <summary>
/// Return the vertical display resolution dpi.
/// </summary>
/// <value>Vertical resolution of the display in dpi.</value>
public abstract int VerticalScreenDPI { get; }
/// <summary>
/// Return the current width of the display in pixels.
/// </summary>
/// <value>Float value equal to the current width of the display in pixels.</value>
public abstract float Width { get; }
#endregion Properties
#region Methods
/// <summary>
/// Add a quad to the rendering queue.
/// </summary>
/// <remarks>
/// All clipping and other adjustments should have been made prior to calling this.
/// </remarks>
/// <param name="destRect">Rect object describing the destination area (values are in pixels).</param>
/// <param name="z">Value specifying the z co-ordinate / z order of the quad.</param>
/// <param name="texture">Texture object that holds the imagery to be rendered.</param>
/// <param name="textureRect">The area of <paramref name="texture"/> that is to be rendered (values are in texture co-ordinates).</param>
/// <param name="colors">\Object describing the colour values that are to be applied when rendering.</param>
public abstract void AddQuad(Rect destRect, float z, Texture texture, Rect textureRect, ColorRect colors);
/// <summary>
/// Clears all queued quads from the render queue.
/// </summary>
public abstract void ClearRenderList();
/// <summary>
/// Creates a 'null' Texture object.
/// </summary>
/// <returns>
/// A newly created Texture object. The returned Texture object has no size or imagery associated with it, and is
/// generally of little or no use.
/// </returns>
public abstract Texture CreateTexture();
/// <summary>
/// Create a <see cref="Texture"/> object using the given image file name.
/// </summary>
/// <remarks>
/// Textures are always created with a size that is a power of 2. If the file you specify is of a size that is not
/// a power of two, the final size will be rounded up. Additionally, textures are always square, so the ultimate
/// size is governed by the larger of the width and height of the specified file. You can check the ultimate sizes
/// by querying the texture after creation.
/// </remarks>
/// <param name="fileName">The path and filename of the image file to use when creating the texture.</param>
/// <returns>A newly created Texture object. The initial contents of the texture memory is the requested image file.</returns>
public abstract Texture CreateTexture(string fileName);
/// <summary>
/// Create a Texture object with the given pixel dimensions as specified by <paramref name="size"/>.
/// </summary>
/// <remarks>
/// Textures are always created with a size that is a power of 2. If you specify a size that is not a power of two, the final
/// size will be rounded up. So if you specify a size of 1024, the texture will be (1024 x 1024), however, if you specify a size
/// of 1025, the texture will be (2048 x 2048). You can check the ultimate size by querying the texture after creation.
/// </remarks>
/// <param name="size">Float value that specifies the size to use for the width and height when creating the new texture.</param>
/// <returns>A newly created Texture object. The initial contents of the texture memory is undefined / random.</returns>
public abstract Texture CreateTexture(float size);
/// <summary>
/// Destroy all texture objects.
/// </summary>
public abstract void DestroyAllTextures();
/// <summary>
/// Destroy the given Texture object.
/// </summary>
/// <param name="texture">Reference to the texture to be destroyed.</param>
public abstract void DestroyTexture(Texture texture);
/// <summary>
/// Perform final rendering for all quads that have been queued for rendering.
/// </summary>
/// <remarks>
/// The contents of the rendering queue is retained and can be rendered again as required.
/// If the contents is not required call <see cref="ClearRenderList"/>.
/// </remarks>
public abstract void DoRender();
#endregion Methods
#endregion Abstract Members
#region Base Members
#region Properties
/// <summary>
/// Return the current Z value to use (equates to layer 0 for this UI element).
/// </summary>
/// <value>float value that specifies the z co-ordinate to be used for layer 0 on the current GUI element.</value>
public float CurrentZ {
get {
return currentZ;
}
}
/// <summary>
/// Enables or disables render queueing.
/// </summary>
/// <value>
/// If false, each call to <see cref="AddQuad"/> will be rendered immediately.
/// If true, calls will be queued and issued in a batch during a <see cref="DoRender"/> call.
/// </value>
public bool QueueingEnabled {
get {
return isQueueingEnabled;
}
set {
isQueueingEnabled = value;
}
}
#endregion Properties
#region Methods
/// <summary>
/// Update the z co-ordinate for the next major UI element (window).
/// </summary>
public void AdvanceZValue() {
currentZ -= GuiZElementStep;
}
/// <summary>
/// Returns the z co-ordinate to use for the requested layer on the current GUI element.
/// </summary>
/// <param name="layer">
/// Specifies the layer to return the Z co-ordinate for. Each GUI element can use up to 10 layers,
/// so valid inputs are 0 to 9 inclusive. If you specify an invalid value, results are undefined.
/// </param>
/// <returns></returns>
public float GetZLayer(int layer) {
// TODO: Throw exception for layer out of range?
return currentZ - ((float) layer * GuiZLayerStep);
}
/// <summary>
/// Reset the z co-ordinate for rendering.
/// </summary>
public void ResetZValue() {
currentZ = GuiZInitialValue;
}
#endregion Methods
#endregion Base Members
}
}
|