Drawing commands

Revision as of 05:10, 30 July 2009

 

Home

 

Download

 

News

 

Support

 

Admin

 

Dev

 

Screen Shots

 

Grid List

 

Bugs

Languages:

English    Deutsch

Technical Reference -> Terms -> Status Page -> OSSL Implemented Functions -> Dynamic textures -> Drawing commands

The drawing commands are strings of text which are concatenated to create a larger string of graphical instructions, which is then passed as a parameter to the dynamic texture drawing functions. With two exceptions, there are convenience functions, such as osDrawRectangle(), provided to assist in building the command list. It is slightly more efficient to directly manipulate the string containing the drawing commands, as it avoids the overhead of multiple function calls (albeit with an arguable loss of readability).

In general, the drawing commands consist of a case-sensitive token which identifies the command, followed by one or more comma-delimited parameters, and terminating in a separator character (a semicolon by default). Whitespace surrounding the commas and/or separator is permitted.

In the examples which follow, it is assumed that CommandList is a string variable which has already been defined within the script source code.

Graphics Primitive Drawing Commands

Ellipse

Ellipse float width, float height;

Draws an ellipse with the current pen size and color.

The ellipse is drawn with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:

CommandList += "Ellipse 100,100;";

FillRectangle

FillRectangle float width, float height;

Draws a rectangle, bordered and filled with the current pen size and color.

The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:

CommandList += "FillRectangle 150,75;";

Image

Image float height, float width, string URL;

Retrieves an image specified by the URL parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively.

If the URL points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the width or height parameters are zero or negative, nothing is drawn, but the image is still retrieved.

Although the width and height parameters accept floating-point values, anything after a decimal point will be ignored.

Example:

CommandList += "Image 293,62,<nowiki>http://opensimulator.org/skins/osmonobook/images/headerLogo.png</nowiki>;";

LineTo

LineTo float x, float y;

Draws a line from the pen's current location to the specified coordinates, using the pen's current color and width.

After the line is drawn, the specified coordinates become the pen's new current location.

Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:

CommandList += "LineTo 640,480;";

MoveTo

MoveTo float x, float y;

Updates the pen's current position to the coordinates provided in the parameters. Nothing is drawn.

Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:

CommandList += "MoveTo 570,23;";

PenColour

PenColour string NewColor;

Sets the pen's drawing color to either the specified named .NET color or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

For full opacity, use an alpha value of ff (e.g. ffff0000 for red); for varying degrees of transparency, reduce the alpha value (e.g. 800000ff for half-transparent blue).

The color names and hexadecimal color representations are not case-sensitive.

Example:

CommandList += "PenColour MidnightBlue;";
CommandList += "PenColour ff191970;";

PenSize

PenSize float width;

Sets the pen size to a square of width pixels by width pixels. If width is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

Although the parameter accepts a floating-point value, anything following a decimal point will be ignored.

Example:

CommandList += "PenSize 5;";

Rectangle

Rectangle float width, float height;

Draws an unfilled rectangle, using the current pen size and color.

The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:

CommandList += "Rectangle 150,75;";

Text Drawing Commands

FontName

FontName string fontname;

Sets the font used by the Text command. If the specified font is not installed on the system, the default font (Arial or its local equivalent) is used.

There is no equivalent convenience function; if you wish to change the font used by the Text command, you must manipulate the string directly.

Example:

CommandList += "FontName Times New Roman;";

FontProp

FontProp string properties;

Sets the text display properties (Regular, Boldface, Underline, Italic and Strikeout) used by subsequent Text calls. The properties are represented by single letters (R,B,U,I and S, respectively), separated by commas. 'R' is a special case which turns off all other properties, while the others are additive.

There is no equivalent convenience function; if you wish to change the properties of the font used by the Text command, you must manipulate the string directly.

Example:

CommandList += "FontProp B,I;";

FontSize

FontSize float size;

Sets the font size used by subsequent Text commands. The size parameter represents the font height in points.

Please note that the font height is given in points, not in pixels. The resulting size of the font in pixels may vary depending on the system settings, specifically the display system's "dots per inch" metric. A system set to 96dpi will produce differently sized text than a system set to 120dpi. If precise text size is required, consider using the osGetDrawStringSize() function to help calculate the proper FontSize value to use (but bear in mind that osGetDrawStringSize() takes an integer parameter for the size, whereas FontSize does use floating-point values).

Unlike the other drawing commands, anything following a decimal point in the size parameter is significant.

If a negative FontSize parameter is specified, any text subsequently added will be displayed upside down and to the right of the point of origin.

Example:

CommandList += "FontSize 12;";

Text

Text string text;

Draws the specified string of text with the current pen color, using the currently defined font, size and properties (which default to regular 14-point Arial).

The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

If you need to include a semicolon in the text to be displayed, you will have to change the command delimiter in the extraParams parameter to the osSetDynamicTexture* functions. However, this will require that all commands be terminated with the alternate delimiter, and you cannot use the convenience functions (which are hardcoded to use a semicolon).

The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

Please note that the pen position is not updated after this call.

Example:

CommandList += "Text Nobody here but us hippos!;";