Difference between revisions of "Mugic/protocol"

Revision as of 14:31, 8 March 2013

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 to both tcp and udp -UDP and TCP streams will work in conjunction and in collaboration with each other -UDP commands have a 1400 byte limit (or whatever the lower limit is of the client and server MAClayer)

User management every tcp connection has a ttl after the ttl time, the scene associated with user will be deleted

Object managment every object has an owner object can be a collection of objects

Syntax

cmd name [parameter={value,`expr`} ...]

expr is a c-style expression

Parameters

cx cy cz

red green blue alpha r g b a

Gradient { circular,linear,exp}

red2 green2 blue2 alpha2

(for linear gradient). gx gy gz (defined as a vector)

rotx roty rotz

scale

scalex scaley scalez

Variables

var name [type={float,array}] [{value,`expr`}, .....]

Variables are created as floats by default. Name of variables follow C variable rules. Variables can be used in expressions

variables of other users can also be accessed as user:variable

parameters of objects can be accessed as variables ObjectName:parameter

the value of a parameter of an object of another user is accessed as

User:ObjectName:parameter

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>

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>

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)

Ellipse

to-do

Box

to-do

Sphere

to-do

Cylinder

to-do

Pyramid

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 ... ]

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

Next Phase

alias (e.g. alias square quad ....... )

move dur=

delete dur=

copy name= src= link name= src= transformation=

Camera Management

Lighting Management

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