Difference between revisions of "Mugic/protocol"
(→Draw Commands) |
m (→Connecting a Client) |
||
(102 intermediate revisions by 4 users not shown) | |||
Line 4: | Line 4: | ||
− | -Server listens to | + | -Server listens and responds to individual clients in raw udp |
− | - | + | -Server also accepts OSC messages, but will not respond in OSC |
-UDP commands have a 1400 byte limit (or whatever the lower limit is of the client and server MAClayer) | -UDP commands have a 1400 byte limit (or whatever the lower limit is of the client and server MAClayer) | ||
− | User management | + | User management: |
− | every | + | every incremental ip connection is assigned the name |
− | + | <user#> (ie user0, user1, user2....) | |
− | Object managment | + | Object managment: |
− | every object has an owner | + | every object has an owner (ie user0:circle1) |
− | + | ||
+ | ==Connecting a Client== | ||
+ | |||
+ | To connect an interactive client to a MUGIC server, you will need to know the IP address of the server as well as the port number it is listening on. Furthermore, you need to be sure that the firewall won't block the connection by adding the port to the list of allowed TCP ports. | ||
+ | |||
+ | nc is a good command line tool to play around with MUGIC and try out a few commands interactively. | ||
+ | |||
+ | 1) Go to the router directory (cd CVRPlugins/calit2/Mugic/router) and run the router (./router). | ||
+ | |||
+ | 2) Run CalVR with the MUGIC plugin enabled (in the config file in the Plugins secion put <Mugic value="on" />. | ||
+ | |||
+ | 3) Open a UDP connection with the following command, assuming nc runs on the same machine as MUGIC, and that it is using the default port of 19997: | ||
+ | |||
+ | <tt>nc -u 127.0.0.1 19997</tt> | ||
+ | |||
+ | 4) Create a default circle with <tt>circle a1</tt>. | ||
+ | |||
+ | 5) If the circle does not immediately show up on the screen, hit View All in CalVR (right-click twice to bring up the menu). | ||
==Syntax== | ==Syntax== | ||
cmd name [parameter={value,`expr`} ...] | cmd name [parameter={value,`expr`} ...] | ||
+ | (needed to create an object: "circle c1 radius=50 x=`c1.radius`") | ||
− | + | or | |
− | + | name [parameter={value,`expr`} ...] | |
− | + | (allowed shorthand if object already exists: "c1 radius=100 x=`-c1.radius`") | |
− | + | ||
− | + | or | |
− | + | name.parameter={value,`expr`}; | |
− | + | (allowed shorthand to single parameter if object already exists: "c1.radius=150; c1.x=`c1.radius/2`") | |
− | + | or | |
− | + | variable={value,`expr`}; | |
+ | (allowed shorthand to create a user variable: "var x=5;" IS THE SAME AS "x=5;" ) | ||
− | + | ==Expressions== | |
+ | <I> expr </I> is a c-style expression | ||
− | + | Expressions and/or variable references are always signified by using the [http://www.thefreedictionary.com/grave+accent grave accent], which is the other thing on your keyboard's [http://www.merriam-webster.com/dictionary/tilde tilde key ~] | |
− | + | ''circle c1; circle c2=`sin(c1.x)^2`;'' | |
− | + | Expressions come by way of ExprTk, and thus our expressions' full capabilities are | |
+ | [http://www.partow.net/programming/exprtk/index.html outlined here.] | ||
− | == Variables == | + | === Variables === |
− | var name | + | var name=[{value,`expr`, "string"}, .....] |
− | + | or | |
− | variables of other users can also be accessed as | + | name=[{value,`expr`, "string"}, .....] |
+ | |||
+ | Variables are created as float values, an expression, or a string. Variables can be used in expressions. Generally name of variables follow C variable rules. | ||
+ | If a value of an expression starts with a number it is treated at a double value; if the value starts with a backquote '`' it is treated as an expression, and if it starts with a double quote '"' it is treated as a string. (variable as strings are currently unstable and their usage is discouraged) | ||
+ | |||
+ | ''var double1=5; var expr1=`5+double1`; var string1="hello there"'' | ||
+ | |||
+ | Parameters of objects can be accessed as variables by using the dot '.' operator with the following syntax: <BR> | ||
+ | ObjectName.ParameterName | ||
+ | |||
+ | Variables of other users can also be accessed as <BR> | ||
user:variable | user:variable | ||
− | + | Thus, the value of a parameter of an object of another user is accessed as | |
− | + | ||
− | + | User:ObjectName.ParameterName | |
− | + | ''circle c1 radius=`user2:c1.radius`'' | |
− | == | + | ====Examples==== |
+ | <pre> | ||
+ | <John:var> refers to the variable "var" of the user "John" | ||
+ | </pre> | ||
+ | <pre> | ||
+ | <John:c1.radius> refers to the value of the "radius" parameter of the object "c1" of the user "john" | ||
+ | </pre> | ||
− | |||
− | + | ====Mode of Operation==== | |
+ | Attempts at setting an unsupported parameter is an error, however, any prior parameter setting in the command block will be applied up to the error location. Thus the command: | ||
+ | <pre> | ||
+ | square s1 x=10 radius=100 y=20 | ||
+ | </pre> | ||
+ | |||
+ | will create a square shape with 'x' set at 20, however, an error will be reported for setting the radius (as the 'square' shape does not support the parameter 'radius') and the parameter 'y' will NOT be set to 20. | ||
+ | |||
+ | == Connections == | ||
+ | |||
+ | user <username> | ||
== User Management and Preferences == | == User Management and Preferences == | ||
pref [cmd] [parameter=value] | pref [cmd] [parameter=value] | ||
− | default object | + | default object {parameter={value,`expr`], ... ] |
− | == Draw Commands == | + | ==Draw Commands== |
− | === Point=== | + | All geometry lives in a 3D space. To keep the geometry in a plane to emulate 2D, set one of the three coordinates to zero. |
+ | |||
+ | By convention, CalVR uses a coordinate system in which x extends to the right, y goes forward, and z is up. If a different coordinate system should be used, the ScreenConfig values in CalVR have to be changed accordingly. | ||
+ | |||
+ | All draw commands can use an optional <tt>name</tt> parameter to set a name for the geometry, which can later be referenced, for instance to update some of its parameters, such as position to move it. The name has to follow the rules for C++ variable names. Examples for valid names: test, Test, test3, test_5, test4me. Examples for invalid names: 4test, test 5, test[4]me. | ||
+ | |||
+ | <BR> | ||
+ | In this specification, 3D positions will be abbreviated by POSITION and can be specified either separately as <pre>x=<xpos> y=<ypos> z=<zpos></pre> | ||
+ | or more compact as <pre>xyz=<xpos>,<ypos>,<zpos></pre> | ||
+ | In either case, the parameters <xpos>, <ypos> and <zpos> are the coordinates in millimeters. The compact form is derived from the GLSL shader language. | ||
+ | |||
+ | '''Note:''' using xyz positions changes the position of the model relative to the center of the model - for example, if an airplane model's center was initially in the body area, and one specifies xyz so that the previous center is now located somewhere in the cockpit area, then the cockpit has become the new centerpoint of the model. This means all translation, scaling, and most importantly rotation commands are done to the model with this centerpoint as a base. If you simply wish to translate a model within the world, use the translation command - this way a model will still rotate about its original origin. | ||
+ | |||
+ | <BR> | ||
+ | '''Colors''' will be abbreviated by COLOR and can be specified either separately as <pre>r=<red> g=<green> b=<blue></pre> | ||
+ | or more compact as <pre>rgb=<red>,<green>,<blue></pre> | ||
+ | In either case, the parameters <red>, <green> and <blue> are the coordinates as floating point numbers in the range of 0 to 1. 0 means lowest intensity, 1 means highest intensity. | ||
+ | |||
+ | If an alpha value is to be specified it can be done in one of these forms: | ||
+ | <pre> | ||
+ | r=<red> g=<green> b=<blue> a=<alpha> | ||
+ | rgba=<red>,<green>,<blue>,<alpha> | ||
+ | </pre> | ||
+ | In either case, <alpha> specifies the alpha value as a floating point value ranging from 0 for invisible to 1 for opaque. | ||
+ | |||
+ | <BR> | ||
+ | '''Textures''' can only be assigned to objects below which specify that they can use textures. For textures, keep all texture images in one folder - the path to this folder must be specified within the mycalvr.xml file with this syntax under the mugic tag: | ||
+ | <pre> | ||
+ | <Mugic> | ||
+ | <Texture dir="texture folder path here" /> | ||
+ | </Mugic> | ||
+ | </pre> | ||
+ | When specifying a texture for an object, simply give the name of the file along with the extension: | ||
+ | <pre> | ||
+ | texture=my_texture.png | ||
+ | </pre> | ||
+ | |||
+ | <BR> | ||
+ | '''Texture coordinates''' also can only be maniuplated with objects that specify they can do so below. Depending on the number of vertices for the object, there will be 1~4 texture points which can be set. Texture coordinates work on a grid system, where s indicates the x-axis(horizontal) coordinate of a point, and t indicates the y-axis(vertical) coordinate of a point. The values of the points can only run from [0,0] (indicating the bottom-leftmost corner of the image) to [1,1] (indicating the top-rightmost corner of the image). So, for example, if you specify | ||
+ | <pre> | ||
+ | rectangle name texture=my_texture.png s1=0.5 t1=0.5 | ||
+ | </pre> | ||
+ | then the bottom left corner of your rectangle will have the texture coordinate [0.5,0.5], which would be the very center of the image my_texture.png. | ||
+ | By default, texture coordinates are set for the best fit of the image - so quads and rectangles take up the entirety of the image, circles and triangles are placed within the center of the image. Cubes require some extra preparation with the image in order to have a box-like texture with different sides - by default, cube texture cuts out a flattened-out box shape from the specified image. | ||
+ | |||
+ | <BR> | ||
+ | For '''models''', keep them all in one folder, like textures, and this path must also be specified within mycalvr.xml: | ||
+ | <pre> | ||
+ | <Mugic> | ||
+ | <Model dir="model folder path here" /> | ||
+ | </Mugic> | ||
+ | </pre> | ||
+ | |||
+ | <BR> | ||
+ | '''Shaders''', both vertex and fragment, work on any 3D object (meaning not point,line, or text). The syntax is | ||
+ | <pre> | ||
+ | rectangle r vertex=myvertex.vert fragment=myfragment.frag | ||
+ | </pre> | ||
+ | can work with just a vertex, or a fragment shader, but if both are working in tandem, it is recommended to set them both at the same time. | ||
+ | |||
+ | '''Note:'''Currently not working with loaded models, although code exists for it. | ||
+ | |||
+ | ===Point=== | ||
Draws a point (single pixel). | Draws a point (single pixel). | ||
;Syntax | ;Syntax | ||
− | :point name=<name> | + | :point name=<name> POSITION COLOR |
− | :point name=<name> | + | :point name=<name> POSITION COLOR |
− | + | ===Triangle=== | |
− | + | ||
− | + | ||
− | + | ||
− | + | Defines vertex coordinates and per-vertex colors for a triangle. | |
;Syntax | ;Syntax | ||
− | :triangle name=<name> | + | :triangle name=<name> xyz1=<xpos1>,<ypos1>,<zpos1> xyz2=<xpos2>,<ypos2>,<zpos2>, xyz3=<xpos3>,<ypos3>,<zpos3> rgb=<red>,<green>,<blue> |
− | + | :triangle name=<name> xyz1=<xpos1>,<ypos1>,<zpos1> xyz2=<xpos2>,<ypos2>,<zpos2>, xyz3=<xpos3>,<ypos3>,<zpos3> rgb1=<red1>,<green1>,<blue1> rgb2=<red2>,<green2>,<blue2> rgb3=<red3>,<green3>,<blue3> | |
+ | :triangle name=<name> texture=<texture> s1=<point1s> t1=<point1t> s2=<point2s> t2=<point2t> s3=<point3s> t3=<point3t> | ||
− | + | ;Parameters | |
+ | :xyz1,xyz2,xyz3: GLSL-style compact form to set all three coordinates for each vertex | ||
+ | :rgb: GLSL-style compact form to set all three color components to be applied to all three vertices (produces single-colored triangle) | ||
+ | :rgb1,rgb2,rgb3: GLSL-style compact form to set all three color components for each vertex | ||
+ | :texture: sets the image texture for the triangle | ||
+ | :s1,s2,s3: sets the horizontal axis texture coordinate for each point (lower left is point1, lower right is point2, top is point 3) | ||
+ | :t1,t2,t3: sets the vertical axis texture coordinate for each point | ||
− | + | ===Quad=== | |
− | + | Draws a quadrangle by creating an OpenGL GL_QUAD object. Note that if all four vertices are not in one plane, intersections of the quad with other geometry might produce unexpected results. | |
− | + | ;Syntax | |
+ | :quad name=<name> xyz1=<xpos1>,<ypos1>,<zpos1> xyz2=<xpos2>,<ypos2>,<zpos2>, xyz3=<xpos3>,<ypos3>,<zpos3> xyz4=<xpos4>,<ypos4>,<zpos4> COLOR | ||
+ | :quad name=<name> texture=<texture> s1=<point1s> t1=<point1t> s2=<point2s> t2=<point2t> s3=<point3s> t3=<point3t> s4=<point4s> t4=<point4t> | ||
− | + | ;Parameters | |
+ | :Analogous to Triangle | ||
+ | :Texture points are bottom left point1, bottom right point2, top right point3, and top left point4 | ||
− | + | ===Rectangle=== | |
− | + | Draws a solid-colored, axis-parallel 2D rectangle. Its origin is in its geometrical center. | |
− | + | ;Syntax: | |
+ | :rectangle name=<name> POSITION width=<width> height=<height> COLOR | ||
+ | :rectangle name=<name> texture=<texture> s1=<point1s> etc... | ||
− | + | ;Parameters: | |
+ | :width: extent along x axis [millimeters] | ||
+ | :height: extent along y axis [millimeters] | ||
+ | :texture: sets image texture for rectangle | ||
+ | :s1,s2,s3,s4: horizontal axis texture coordinates | ||
+ | :t1,t2,t3,t4: vertical axis texture coordinates | ||
+ | :Texture points are lower left point1, lower right point2, upper right point3, upper left point4 | ||
− | Draws | + | ===Circle=== |
+ | |||
+ | Draws a flat, solid-filled circle with its center at POSITION. | ||
;Syntax: | ;Syntax: | ||
− | : | + | :circle name=<name> POSITION radius=<radius> COLOR |
+ | :circle name=<name> texture=<texture> texcenters=<centerpoint s> texcentert=<centerpoint t> texrad=<texture radius> | ||
;Parameters: | ;Parameters: | ||
− | : | + | :radius: circle radius [millimeters] |
− | : | + | :texture: image texture for circle |
− | : | + | :texcenters,texcentert: sets the horizontal,vertical texture point for the center of the circle |
+ | :texrad: sets the radius of texture from center (must be <= distance between center point texture coordinate and closest edge) | ||
− | === | + | === Sphere === |
− | radius | + | Draws a sphere with the specified radius. |
− | == | + | ;Syntax: |
+ | :sphere name=<name> POSITION COLOR radius=<radius> | ||
− | + | ;Parameters: | |
+ | :radius sets the radius of the sphere. | ||
+ | Textures cannot be applied. | ||
− | === | + | === Cylinder === |
+ | Draws a cylinder with the specified radius and height. | ||
+ | ;Syntax: | ||
+ | :cylinder name=<name> POSITION COLOR radius=<radius> height=<height> | ||
− | + | ;Parameters: | |
+ | :radius sets the radius of the cylinder. | ||
+ | :height set the vertical height of the cylinder. | ||
+ | Textures cannot be applied. | ||
− | === | + | === Cone === |
+ | Draws a cone with the specified radius and height. | ||
+ | |||
+ | ;Syntax: | ||
+ | :cone name=<name> POSITION COLOR radius=<radius> height=<height> | ||
+ | |||
+ | ;Parameters: | ||
+ | :radius sets the radius of the base of the cone. | ||
+ | :height set the vertical height of the cone. | ||
+ | Textures cannot be applied. | ||
+ | |||
+ | === Capsule === | ||
+ | Draws a capsule-like shape with the specified radius and height. | ||
+ | |||
+ | ;Syntax: | ||
+ | :capsule name=<name> POSITION COLOR radius=<radius> height=<height> | ||
+ | |||
+ | ;Parameters: | ||
+ | :radius sets the radius of the capsule. | ||
+ | :height set the height of the capsule. | ||
+ | Textures cannot be applied. | ||
=== Pyramid === | === Pyramid === | ||
+ | to-do | ||
+ | === Ellipse === | ||
+ | to-do | ||
+ | |||
+ | === Box === | ||
+ | to-do | ||
+ | |||
+ | === Cube === | ||
+ | Draws a cube, with specified length, width, and height. | ||
+ | |||
+ | ;Syntax: | ||
+ | :cube name=<name> POSITION width=<width> height=<height> depth=<depth> COLOR texture=<texture> | ||
+ | |||
+ | ;Parameters: | ||
+ | :width: extends along x axis | ||
+ | :height: extends along z axis | ||
+ | :depth: extends along y axis | ||
+ | :texture: sets texture image for cube (cannot maniuplate texture coords) | ||
+ | |||
+ | === Model === | ||
+ | Model creates an object from the specified model file, such as a .wrl or .obj. | ||
+ | |||
+ | ;Syntax: | ||
+ | :model name=<name> file=<filename> | ||
+ | |||
+ | ;Parameters: | ||
+ | :file: specifies the name of the model file to be loaded. If nothing is specified, or the model could not be read correctly, a default model is loaded. | ||
=== Update === | === Update === | ||
+ | |||
+ | Updates one or more parameters of a shape object. The update parameters can be references to their previous values. Those parameters that are not modified retain their previous values. | ||
+ | |||
+ | Example: <tt>update name=testobject x=x+100</tt> will move the object by 100 millimeters to the right. | ||
+ | |||
+ | ;Syntax | ||
+ | :update name=<name> POSITION COLOR | ||
+ | |||
+ | ;Parameters | ||
+ | :name: name of previously defined shape | ||
+ | :POSITION: the new position for the object | ||
+ | :COLOR: the new color for the object | ||
+ | |||
+ | ==Transformations== | ||
+ | |||
+ | ===Rotation=== | ||
+ | |||
+ | Rotate an existing object with name <name> by <heading_degrees> degrees about the z-axis, <pitch_degrees> about the x-axis, and <roll_degrees> about the y-axis. If more than one rotation type is given, they are being applied in the following order: pitch, roll, heading. | ||
+ | |||
+ | <tt>rotate <name> head=<heading_degrees> pitch=<pitch_degrees> roll=<roll_degrees></tt> | ||
+ | |||
+ | Successive rotation commands will overwrite (not multiply by) the previously defined rotation. | ||
+ | |||
+ | ===Scaling/Resizing=== | ||
+ | |||
+ | Scale (resize) an existing object with name <name> by a factor of <scale_xyz>. This will scale the object by equal amounts about its origin. Alternatively, non-uniform scaling is possible by scaling along each coordinate axis separately, using the sx, sy and sz parameters. | ||
+ | |||
+ | Uniform scale: | ||
+ | |||
+ | <tt>scale <name> factor=<scale_xyz></tt> | ||
+ | |||
+ | Non-uniform scale: | ||
+ | |||
+ | <tt>scale <name> x=<scale_x> y=<scale_y> z=<scale_z></tt> | ||
+ | |||
+ | Successive scale commands will overwrite (not multiply by) the previously defined scale values. | ||
+ | |||
+ | ===Translation=== | ||
+ | |||
+ | Translate an existing object with name <name> by a factor of <translate_xyz>. This will translate the object relative to the world origin. | ||
+ | |||
+ | <tt>translate <name> x=<trans_x> y=<trans_y> z=<trans_z></tt> | ||
+ | |||
+ | Successive translation commands will overwrite (not add/multiply by) the previously defined translation values. | ||
== group == | == group == | ||
group name [names ... ] | group name [names ... ] | ||
+ | |||
+ | ==Sound== | ||
+ | |||
+ | The audio capabilities are desribed [[MUGIC-Audio-Wrapper | here]]. | ||
==Examples == | ==Examples == | ||
Line 158: | Line 388: | ||
connect user1 | connect user1 | ||
− | var var1=2 | + | var var1 value=2 |
circle name=x1 cx=`-var1` radius=`10000/var1` | circle name=x1 cx=`-var1` radius=`10000/var1` | ||
− | update var1=3000 | + | update var1 value=3000 |
− | update var1=5000 | + | update var1 value=5000 |
− | update var1=10000 | + | update var1 value=10000 |
update x1 cx=`var*1.5` | update x1 cx=`var*1.5` | ||
Line 174: | Line 404: | ||
connect user1 | connect user1 | ||
− | var var1=2000; var var2=2500 | + | var var1 value=2000; var var2 value=2500 |
circle name=c1 cx=`-var1` cy=0 radius=`10000/var1` | circle name=c1 cx=`-var1` cy=0 radius=`10000/var1` | ||
Line 185: | Line 415: | ||
update x1 cx=7000 | update x1 cx=7000 | ||
+ | |||
+ | |||
+ | === Example set 4 === | ||
+ | |||
+ | var x1=5; | ||
+ | |||
+ | var x2=`10*x1`; | ||
+ | |||
+ | circle foo radius=`x2`; | ||
+ | |||
+ | update x1=10; | ||
+ | |||
+ | |||
+ | --------------------------------------- | ||
+ | var x2=5; | ||
+ | |||
+ | var x1=`x2*5`; | ||
+ | |||
+ | var x2=`x1*10`; | ||
+ | |||
+ | Report an error; | ||
+ | |||
+ | ---------------------------------------- | ||
+ | |||
+ | circle foo radius=100; | ||
+ | |||
+ | circle bar radius=`foo.radius * 10`; | ||
+ | |||
+ | circle bar radius=`foo.radius ? 10 : x2*10`; | ||
+ | |||
+ | update foo radius=200 | ||
+ | |||
+ | |||
+ | -------------------------------------------------- | ||
+ | |||
+ | global variables | ||
+ | |||
+ | system.{variable} | ||
+ | |||
+ | e.g., system.time | ||
+ | |||
+ | ---------------------------------------------------- | ||
+ | |||
+ | regular expressions | ||
+ | |||
+ | circle foo1 radius=20 | ||
+ | circle foo2 radius=30 | ||
+ | |||
+ | update foo* radius=10 | ||
+ | |||
+ | -------------------------------------------------- | ||
+ | |||
+ | Video capture | ||
+ | video delay | ||
== Next Phase == | == Next Phase == | ||
Line 193: | Line 477: | ||
delete dur= | delete dur= | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
copy name= src= | copy name= src= | ||
Line 207: | Line 485: | ||
Lighting Management <BR> | Lighting Management <BR> | ||
+ | Shaders for loaded models <BR> | ||
Quad ID=X p1=0,0 p2=1,0 p3=1,1 P4=0,0 | Quad ID=X p1=0,0 p2=1,0 p3=1,1 P4=0,0 | ||
link ID=A src=X | link ID=A src=X | ||
− | |||
move ID= dx=.1 dy=.5 | move ID= dx=.1 dy=.5 | ||
group iD=C A,B | group iD=C A,B |
Latest revision as of 15:05, 27 January 2014
Contents |
Overview
MUGIC defines a protocol for a standard display-independent client/server model for the generation, control, and management of graphics rendering within a multi-user environment. The first implementation for the CalVR system used on the state-of-the-art visualisation technologies developed at Calit2. This protocol will provide ease of access and an integrated development environment for research, education, performance, interaction, and presentations. It will provide an easily accessible format for integration of real-time programming softwares (e.g., Touch Designer, Pure Data, Max/MSP, Quartz, Processing, etc.) which in turn will facilitate the incorporation of state-of-the-art gesture control and algorithmic/generative processes for control of graphics on multiple displays. The protocol will also provide multi-user management and access support, as well as real-time telematic connection between multiple servers materializing an enormous potential for development of multi-site virtual reality game and performance productions.
-Server listens and responds to individual clients in raw udp
-Server also accepts OSC messages, but will not respond in OSC
-UDP commands have a 1400 byte limit (or whatever the lower limit is of the client and server MAClayer)
User management: every incremental ip connection is assigned the name <user#> (ie user0, user1, user2....)
Object managment: every object has an owner (ie user0:circle1)
Connecting a Client
To connect an interactive client to a MUGIC server, you will need to know the IP address of the server as well as the port number it is listening on. Furthermore, you need to be sure that the firewall won't block the connection by adding the port to the list of allowed TCP ports.
nc is a good command line tool to play around with MUGIC and try out a few commands interactively.
1) Go to the router directory (cd CVRPlugins/calit2/Mugic/router) and run the router (./router).
2) Run CalVR with the MUGIC plugin enabled (in the config file in the Plugins secion put <Mugic value="on" />.
3) Open a UDP connection with the following command, assuming nc runs on the same machine as MUGIC, and that it is using the default port of 19997:
nc -u 127.0.0.1 19997
4) Create a default circle with circle a1.
5) If the circle does not immediately show up on the screen, hit View All in CalVR (right-click twice to bring up the menu).
Syntax
cmd name [parameter={value,`expr`} ...] (needed to create an object: "circle c1 radius=50 x=`c1.radius`")
or
name [parameter={value,`expr`} ...] (allowed shorthand if object already exists: "c1 radius=100 x=`-c1.radius`")
or
name.parameter={value,`expr`}; (allowed shorthand to single parameter if object already exists: "c1.radius=150; c1.x=`c1.radius/2`")
or
variable={value,`expr`}; (allowed shorthand to create a user variable: "var x=5;" IS THE SAME AS "x=5;" )
Expressions
expr is a c-style expression
Expressions and/or variable references are always signified by using the grave accent, which is the other thing on your keyboard's tilde key ~
circle c1; circle c2=`sin(c1.x)^2`;
Expressions come by way of ExprTk, and thus our expressions' full capabilities are outlined here.
Variables
var name=[{value,`expr`, "string"}, .....]
or
name=[{value,`expr`, "string"}, .....]
Variables are created as float values, an expression, or a string. Variables can be used in expressions. Generally name of variables follow C variable rules. If a value of an expression starts with a number it is treated at a double value; if the value starts with a backquote '`' it is treated as an expression, and if it starts with a double quote '"' it is treated as a string. (variable as strings are currently unstable and their usage is discouraged)
var double1=5; var expr1=`5+double1`; var string1="hello there"
Parameters of objects can be accessed as variables by using the dot '.' operator with the following syntax:
ObjectName.ParameterName
Variables of other users can also be accessed as
user:variable
Thus, the value of a parameter of an object of another user is accessed as
User:ObjectName.ParameterName
circle c1 radius=`user2:c1.radius`
Examples
<John:var> refers to the variable "var" of the user "John"
<John:c1.radius> refers to the value of the "radius" parameter of the object "c1" of the user "john"
Mode of Operation
Attempts at setting an unsupported parameter is an error, however, any prior parameter setting in the command block will be applied up to the error location. Thus the command:
square s1 x=10 radius=100 y=20
will create a square shape with 'x' set at 20, however, an error will be reported for setting the radius (as the 'square' shape does not support the parameter 'radius') and the parameter 'y' will NOT be set to 20.
Connections
user <username>
User Management and Preferences
pref [cmd] [parameter=value]
default object {parameter={value,`expr`], ... ]
Draw Commands
All geometry lives in a 3D space. To keep the geometry in a plane to emulate 2D, set one of the three coordinates to zero.
By convention, CalVR uses a coordinate system in which x extends to the right, y goes forward, and z is up. If a different coordinate system should be used, the ScreenConfig values in CalVR have to be changed accordingly.
All draw commands can use an optional name parameter to set a name for the geometry, which can later be referenced, for instance to update some of its parameters, such as position to move it. The name has to follow the rules for C++ variable names. Examples for valid names: test, Test, test3, test_5, test4me. Examples for invalid names: 4test, test 5, test[4]me.
x=<xpos> y=<ypos> z=<zpos>or more compact as
xyz=<xpos>,<ypos>,<zpos>
In either case, the parameters <xpos>, <ypos> and <zpos> are the coordinates in millimeters. The compact form is derived from the GLSL shader language.
Note: using xyz positions changes the position of the model relative to the center of the model - for example, if an airplane model's center was initially in the body area, and one specifies xyz so that the previous center is now located somewhere in the cockpit area, then the cockpit has become the new centerpoint of the model. This means all translation, scaling, and most importantly rotation commands are done to the model with this centerpoint as a base. If you simply wish to translate a model within the world, use the translation command - this way a model will still rotate about its original origin.
r=<red> g=<green> b=<blue>or more compact as
rgb=<red>,<green>,<blue>
In either case, the parameters <red>, <green> and <blue> are the coordinates as floating point numbers in the range of 0 to 1. 0 means lowest intensity, 1 means highest intensity.
If an alpha value is to be specified it can be done in one of these forms:
r=<red> g=<green> b=<blue> a=<alpha> rgba=<red>,<green>,<blue>,<alpha>
In either case, <alpha> specifies the alpha value as a floating point value ranging from 0 for invisible to 1 for opaque.
Textures can only be assigned to objects below which specify that they can use textures. For textures, keep all texture images in one folder - the path to this folder must be specified within the mycalvr.xml file with this syntax under the mugic tag:
<Mugic> <Texture dir="texture folder path here" /> </Mugic>
When specifying a texture for an object, simply give the name of the file along with the extension:
texture=my_texture.png
Texture coordinates also can only be maniuplated with objects that specify they can do so below. Depending on the number of vertices for the object, there will be 1~4 texture points which can be set. Texture coordinates work on a grid system, where s indicates the x-axis(horizontal) coordinate of a point, and t indicates the y-axis(vertical) coordinate of a point. The values of the points can only run from [0,0] (indicating the bottom-leftmost corner of the image) to [1,1] (indicating the top-rightmost corner of the image). So, for example, if you specify
rectangle name texture=my_texture.png s1=0.5 t1=0.5
then the bottom left corner of your rectangle will have the texture coordinate [0.5,0.5], which would be the very center of the image my_texture.png. By default, texture coordinates are set for the best fit of the image - so quads and rectangles take up the entirety of the image, circles and triangles are placed within the center of the image. Cubes require some extra preparation with the image in order to have a box-like texture with different sides - by default, cube texture cuts out a flattened-out box shape from the specified image.
For models, keep them all in one folder, like textures, and this path must also be specified within mycalvr.xml:
<Mugic> <Model dir="model folder path here" /> </Mugic>
Shaders, both vertex and fragment, work on any 3D object (meaning not point,line, or text). The syntax is
rectangle r vertex=myvertex.vert fragment=myfragment.frag
can work with just a vertex, or a fragment shader, but if both are working in tandem, it is recommended to set them both at the same time.
Note:Currently not working with loaded models, although code exists for it.
Point
Draws a point (single pixel).
- Syntax
- point name=<name> POSITION COLOR
- point name=<name> POSITION COLOR
Triangle
Defines vertex coordinates and per-vertex colors for a triangle.
- Syntax
- triangle name=<name> xyz1=<xpos1>,<ypos1>,<zpos1> xyz2=<xpos2>,<ypos2>,<zpos2>, xyz3=<xpos3>,<ypos3>,<zpos3> rgb=<red>,<green>,<blue>
- triangle name=<name> xyz1=<xpos1>,<ypos1>,<zpos1> xyz2=<xpos2>,<ypos2>,<zpos2>, xyz3=<xpos3>,<ypos3>,<zpos3> rgb1=<red1>,<green1>,<blue1> rgb2=<red2>,<green2>,<blue2> rgb3=<red3>,<green3>,<blue3>
- triangle name=<name> texture=<texture> s1=<point1s> t1=<point1t> s2=<point2s> t2=<point2t> s3=<point3s> t3=<point3t>
- Parameters
- xyz1,xyz2,xyz3: GLSL-style compact form to set all three coordinates for each vertex
- rgb: GLSL-style compact form to set all three color components to be applied to all three vertices (produces single-colored triangle)
- rgb1,rgb2,rgb3: GLSL-style compact form to set all three color components for each vertex
- texture: sets the image texture for the triangle
- s1,s2,s3: sets the horizontal axis texture coordinate for each point (lower left is point1, lower right is point2, top is point 3)
- t1,t2,t3: sets the vertical axis texture coordinate for each point
Quad
Draws a quadrangle by creating an OpenGL GL_QUAD object. Note that if all four vertices are not in one plane, intersections of the quad with other geometry might produce unexpected results.
- Syntax
- quad name=<name> xyz1=<xpos1>,<ypos1>,<zpos1> xyz2=<xpos2>,<ypos2>,<zpos2>, xyz3=<xpos3>,<ypos3>,<zpos3> xyz4=<xpos4>,<ypos4>,<zpos4> COLOR
- quad name=<name> texture=<texture> s1=<point1s> t1=<point1t> s2=<point2s> t2=<point2t> s3=<point3s> t3=<point3t> s4=<point4s> t4=<point4t>
- Parameters
- Analogous to Triangle
- Texture points are bottom left point1, bottom right point2, top right point3, and top left point4
Rectangle
Draws a solid-colored, axis-parallel 2D rectangle. Its origin is in its geometrical center.
- Syntax
- rectangle name=<name> POSITION width=<width> height=<height> COLOR
- rectangle name=<name> texture=<texture> s1=<point1s> etc...
- Parameters
- width: extent along x axis [millimeters]
- height: extent along y axis [millimeters]
- texture: sets image texture for rectangle
- s1,s2,s3,s4: horizontal axis texture coordinates
- t1,t2,t3,t4: vertical axis texture coordinates
- Texture points are lower left point1, lower right point2, upper right point3, upper left point4
Circle
Draws a flat, solid-filled circle with its center at POSITION.
- Syntax
- circle name=<name> POSITION radius=<radius> COLOR
- circle name=<name> texture=<texture> texcenters=<centerpoint s> texcentert=<centerpoint t> texrad=<texture radius>
- Parameters
- radius: circle radius [millimeters]
- texture: image texture for circle
- texcenters,texcentert: sets the horizontal,vertical texture point for the center of the circle
- texrad: sets the radius of texture from center (must be <= distance between center point texture coordinate and closest edge)
Sphere
Draws a sphere with the specified radius.
- Syntax
- sphere name=<name> POSITION COLOR radius=<radius>
- Parameters
- radius sets the radius of the sphere.
Textures cannot be applied.
Cylinder
Draws a cylinder with the specified radius and height.
- Syntax
- cylinder name=<name> POSITION COLOR radius=<radius> height=<height>
- Parameters
- radius sets the radius of the cylinder.
- height set the vertical height of the cylinder.
Textures cannot be applied.
Cone
Draws a cone with the specified radius and height.
- Syntax
- cone name=<name> POSITION COLOR radius=<radius> height=<height>
- Parameters
- radius sets the radius of the base of the cone.
- height set the vertical height of the cone.
Textures cannot be applied.
Capsule
Draws a capsule-like shape with the specified radius and height.
- Syntax
- capsule name=<name> POSITION COLOR radius=<radius> height=<height>
- Parameters
- radius sets the radius of the capsule.
- height set the height of the capsule.
Textures cannot be applied.
Pyramid
to-do
Ellipse
to-do
Box
to-do
Cube
Draws a cube, with specified length, width, and height.
- Syntax
- cube name=<name> POSITION width=<width> height=<height> depth=<depth> COLOR texture=<texture>
- Parameters
- width: extends along x axis
- height: extends along z axis
- depth: extends along y axis
- texture: sets texture image for cube (cannot maniuplate texture coords)
Model
Model creates an object from the specified model file, such as a .wrl or .obj.
- Syntax
- model name=<name> file=<filename>
- Parameters
- file: specifies the name of the model file to be loaded. If nothing is specified, or the model could not be read correctly, a default model is loaded.
Update
Updates one or more parameters of a shape object. The update parameters can be references to their previous values. Those parameters that are not modified retain their previous values.
Example: update name=testobject x=x+100 will move the object by 100 millimeters to the right.
- Syntax
- update name=<name> POSITION COLOR
- Parameters
- name: name of previously defined shape
- POSITION: the new position for the object
- COLOR: the new color for the object
Transformations
Rotation
Rotate an existing object with name <name> by <heading_degrees> degrees about the z-axis, <pitch_degrees> about the x-axis, and <roll_degrees> about the y-axis. If more than one rotation type is given, they are being applied in the following order: pitch, roll, heading.
rotate <name> head=<heading_degrees> pitch=<pitch_degrees> roll=<roll_degrees>
Successive rotation commands will overwrite (not multiply by) the previously defined rotation.
Scaling/Resizing
Scale (resize) an existing object with name <name> by a factor of <scale_xyz>. This will scale the object by equal amounts about its origin. Alternatively, non-uniform scaling is possible by scaling along each coordinate axis separately, using the sx, sy and sz parameters.
Uniform scale:
scale <name> factor=<scale_xyz>
Non-uniform scale:
scale <name> x=<scale_x> y=<scale_y> z=<scale_z>
Successive scale commands will overwrite (not multiply by) the previously defined scale values.
Translation
Translate an existing object with name <name> by a factor of <translate_xyz>. This will translate the object relative to the world origin.
translate <name> x=<trans_x> y=<trans_y> z=<trans_z>
Successive translation commands will overwrite (not add/multiply by) the previously defined translation values.
group
group name [names ... ]
Sound
The audio capabilities are desribed here.
Examples
Example 1
connect user1
circle name=cir1 cx=1000 cy=2000 radius=3000
sphere name=xph1 cx=1000 cy=2000 cz=3000 radius=1000
Example 2
connect user1
var var1 value=2
circle name=x1 cx=`-var1` radius=`10000/var1`
update var1 value=3000
update var1 value=5000
update var1 value=10000
update x1 cx=`var*1.5`
Example 3
connect user1
var var1 value=2000; var var2 value=2500
circle name=c1 cx=`-var1` cy=0 radius=`10000/var1`
square name=s1 cx=`var1` cy=0 width=`abs((2*var-10000/var1)/2)`
group x1 c1 s1
update x1 cx=5000
update x1 cx=7000
Example set 4
var x1=5;
var x2=`10*x1`;
circle foo radius=`x2`;
update x1=10;
var x2=5;
var x1=`x2*5`;
var x2=`x1*10`;
Report an error;
circle foo radius=100;
circle bar radius=`foo.radius * 10`;
circle bar radius=`foo.radius ? 10 : x2*10`;
update foo radius=200
global variables
system.{variable}
e.g., system.time
regular expressions
circle foo1 radius=20 circle foo2 radius=30
update foo* radius=10
Video capture video delay
Next Phase
alias (e.g. alias square quad ....... )
move dur=
delete dur=
copy name= src= link name= src= transformation=
Camera Management
Lighting Management
Shaders for loaded models
Quad ID=X p1=0,0 p2=1,0 p3=1,1 P4=0,0 link ID=A src=X move ID= dx=.1 dy=.5 group iD=C A,B