Drawing commands

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(added link to Font Families which are safe to use)
(5 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:Quicklinks}}
+
{{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).
 
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).
Line 10: Line 7:
 
In the examples which follow, it is assumed that ''CommandList'' is a string variable which has already been defined within the script source code.
 
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 ==
  
===Ellipse===
+
=== Ellipse ===
  
 
;Ellipse float width, float height;
 
;Ellipse float width, float height;
Line 27: Line 24:
  
  
===Polygon===
+
=== FillEllipse ===
 +
 
 +
;FillEllipse float width, float height;
 +
:Draws an filled 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:
 +
:<source lang="lsl">
 +
CommandList += "FillEllipse 100,100;";
 +
</source>
 +
 
 +
 
 +
=== Polygon ===
 
;Polygon string xpoints, string ypoints;
 
;Polygon string xpoints, string ypoints;
 
:Draws an unfilled polygon, using current pen size and color.
 
:Draws an unfilled polygon, using current pen size and color.
Line 39: Line 51:
  
  
===FillPolygon===
+
=== FillPolygon ===
 
;FillPolygon string xpoints, string ypoints;
 
;FillPolygon string xpoints, string ypoints;
 
:Draws a filled polygon, using current pen size and color.
 
:Draws a filled polygon, using current pen size and color.
Line 51: Line 63:
  
  
===Rectangle===
+
=== Rectangle ===
  
 
;Rectangle float width, float height;
 
;Rectangle float width, float height;
Line 66: Line 78:
  
  
===FillRectangle===
+
=== FillRectangle ===
  
 
;FillRectangle float width, float height;
 
;FillRectangle float width, float height;
Line 81: Line 93:
  
  
===Image===
+
=== Image ===
  
 
;Image float height, float width, string URL;
 
;Image float height, float width, string URL;
Line 96: Line 108:
  
  
===LineTo===
+
=== LineTo ===
  
 
;LineTo float x, float y;
 
;LineTo float x, float y;
Line 111: Line 123:
  
  
===MoveTo===
+
=== MoveTo ===
  
 
;MoveTo float x, float y;
 
;MoveTo float x, float y;
Line 124: Line 136:
  
  
===PenColour===
+
=== PenColour ===
  
 
;PenColour string NewColor;
 
;PenColour string NewColor;
Line 140: Line 152:
  
  
===PenSize===
+
=== PenSize ===
  
 
;PenSize float width;
 
;PenSize float width;
Line 153: Line 165:
  
  
===PenCap===
+
=== PenCap ===
  
 
;PenCap string direction, string type;
 
;PenCap string direction, string type;
Line 159: Line 171:
 
:Sets the pens cap start, end or both to a cap style.  
 
:Sets the pens cap start, end or both to a cap style.  
  
:Possible values for direction are (case-insensitive): <b>"start", "end", "both"</b>
+
:Possible values for direction are (case-insensitive): '''"start", "end", "both"'''
  
:Possible values for type are (case-insensitive): <b>"arrow","diamond","round","flat"</b>(default)
+
:Possible values for type are (case-insensitive): '''"arrow","diamond","round","flat"'''(default)
  
 
Example:
 
Example:
Line 168: Line 180:
 
</source>
 
</source>
  
==Text Drawing Commands==
+
== Text Drawing Commands ==
  
=== FontName ===
+
=== FontName ===
  
 
;FontName string 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.
 
: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.
  
<br>
+
<br />
  
 
: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.
 
: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.
  
<br>
+
<br />
  
:For font families which can be used SEE: [http://www.w3schools.com/css/css_websafe_fonts.asp www.w3schools.com/css/css_websafe_fonts.asp]
+
:For font families which can be used, see: [http://www.w3schools.com/css/css_websafe_fonts.asp www.w3schools.com/css/css_websafe_fonts.asp]
  
 
:Example:  
 
:Example:  
Line 188: Line 200:
 
</source>
 
</source>
  
===FontProp===
+
=== FontProp ===
  
 
;FontProp string properties;
 
;FontProp string properties;
Line 201: Line 213:
  
  
===FontSize===
+
=== FontSize ===
  
 
;FontSize float size;
 
;FontSize float size;
 
:Sets the font size used by subsequent '''[[#Text|Text]]''' commands. The '''size''' parameter represents the font height in points.  
 
: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).
+
: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.
 
:Unlike the other drawing commands, anything following a decimal point in the '''size''' parameter is significant.
Line 217: Line 229:
 
</source>
 
</source>
  
===Text===
+
=== Text ===
  
 
;Text string text;
 
;Text string text;
Line 234: Line 246:
 
CommandList += "Text Nobody here but us hippos!;";
 
CommandList += "Text Nobody here but us hippos!;";
 
</source>
 
</source>
 
  
 
[[Category:OSSL]]
 
[[Category:OSSL]]
 
[[Category:Scripting]]
 
[[Category:Scripting]]

Revision as of 03:25, 24 June 2017

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.

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


FillEllipse

FillEllipse float width, float height;
Draws an filled 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 += "FillEllipse 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)

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.


For font families which can be used, see: www.w3schools.com/css/css_websafe_fonts.asp
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!;";
Personal tools
General
About This Wiki