Drawing commands

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
m (→‎FontSize: Clarify wording)
Line 1: Line 1:
−
{{Template:Quicklinks}}
 
−
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| 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 textures|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==
 
==Graphics Primitive Drawing Commands==
  
Line 23: Line 13:
 
:<source lang="lsl">
 
:<source lang="lsl">
 
CommandList += "Ellipse 100,100;";
 
CommandList += "Ellipse 100,100;";
 +
</source>
 +
 +
 +
===Polygon===
 +
;Polygon string xpoints, string ypoints;
 +
:Draws an unfilled polygon, using current pen size and color.
 +
 +
:The polygon is drawn following a sequence of x and y points given to the method (in the order that they are given), finally closing in the first one. Although the parameters accept floating-point values, anything after a decimal point will be ignored.
 +
 +
Example:
 +
:<source lang="lsl">
 +
CommandList += "Polygon 50,50,100,100,50,150,50;"; // This creates a triangle using points (50,50)(100,100)(150,50)
 +
</source>
 +
 +
 +
===FillPolygon===
 +
;FillPolygon string xpoints, string ypoints;
 +
:Draws a filled polygon, using current pen size and color.
 +
 +
:The polygon is drawn following a sequence of x and y points (in pixels) given to the method (in the order that they are given), finally closing in the first. Although the parameters accept floating-point values, anything after a decimal point will be ignored.
 +
 +
Example:
 +
:<source lang="lsl">
 +
CommandList += "FillPolygon 50,50,100,100,50,150,50;"; // This creates a triangle using points (50,50)(100,100)(150,50)
 +
</source>
 +
 +
 +
===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:
 +
:<source lang="lsl">
 +
CommandList += "Rectangle 150,75;";
 
</source>
 
</source>
  
Line 113: Line 142:
  
  
−
===Rectangle===
+
===PenCap===
−
 
+
−
;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:
+
−
:<source lang="lsl">
+
−
CommandList += "Rectangle 150,75;";
+
−
</source>
+
−
 
+
−
 
+
−
==Text Drawing Commands==
+
−
 
+
−
===FontName===
+
−
 
+
−
;FontName string fontname;
+
−
:Sets the font used by the '''[[#Text|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|Text]]''' command, you must manipulate the string directly.
+
−
 
+
−
Example:
+
−
:<source lang="lsl">
+
−
CommandList += "FontName Times New Roman;";
+
−
</source>
+
−
 
+
−
 
+
−
===FontProp===
+
−
 
+
−
;FontProp string properties;
+
−
:Sets the text display properties (Regular, Boldface, Underline, Italic and Strikeout) used by subsequent '''[[#Text|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|Text]]''' command, you must manipulate the string directly.
+
−
 
+
−
Example:
+
−
:<source lang="lsl">
+
−
CommandList += "FontProp B,I;";
+
−
</source>
+
−
 
+
−
 
+
−
===FontSize===
+
−
 
+
−
;FontSize float size;
+
−
:Sets the font size used by subsequent '''[[#Text|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:
+
−
:<source lang="lsl">
+
−
CommandList += "FontSize 12;";
+
−
</source>
+
−
 
+
−
===Text===
+
−
 
+
−
;Text string text;
+
−
:Draws the specified string of text with the current pen color, using the currently defined [[#FontName|font]], [[#FontSize|size]] and [[#FontProp|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 <tt>extraParams</tt> 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).
+
;PenCap string direction, string type;
 +
:ATTENTION: THIS METHOD WORKS ONLY ON .NET, MONO DOES NOT HAVE CAPS CORRECTLY IMPLEMENTED ON LIBGDI+
 +
:Sets the pens cap start, end or both to a cap style.  
  
−
: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.
+
:Possible values for direction are (case-insensitive): <b>"start", "end", "both"</b>
  
−
:Please note that the pen position is ''not'' updated after this call.
+
:Possible values for type are (case-insensitive): <b>"arrow","diamond","round","flat"</b>(default)
  
 
Example:
 
Example:
 
:<source lang="lsl">
 
:<source lang="lsl">
−
CommandList += "Text Nobody here but us hippos!;";
+
CommandList += "PenCap start,arrow;"; //Draws an arrow at the end of the next line drawn (with LineTo)
 
</source>
 
</source>

Revision as of 05:39, 31 August 2009

Contents

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;";


Polygon

Polygon string xpoints, string ypoints;
Draws an unfilled polygon, using current pen size and color.
The polygon is drawn following a sequence of x and y points given to the method (in the order that they are given), finally closing in the first one. Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example: 

CommandList += "Polygon 50,50,100,100,50,150,50;"; // This creates a triangle using points (50,50)(100,100)(150,50)


FillPolygon

FillPolygon string xpoints, string ypoints;
Draws a filled polygon, using current pen size and color.
The polygon is drawn following a sequence of x and y points (in pixels) given to the method (in the order that they are given), finally closing in the first. Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example: 

CommandList += "FillPolygon 50,50,100,100,50,150,50;"; // This creates a triangle using points (50,50)(100,100)(150,50)


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;";


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;";


PenCap

PenCap string direction, string type;
ATTENTION: THIS METHOD WORKS ONLY ON .NET, MONO DOES NOT HAVE CAPS CORRECTLY IMPLEMENTED ON LIBGDI+
Sets the pens cap start, end or both to a cap style.
Possible values for direction are (case-insensitive): "start", "end", "both"
Possible values for type are (case-insensitive): "arrow","diamond","round","flat"(default)

Example: 

CommandList += "PenCap start,arrow;"; //Draws an arrow at the end of the next line drawn (with LineTo)
Retrieved from "http://opensimulator.org/index.php?title=Drawing_commands&oldid=14783"
Personal tools
General
About This Wiki