Introduction to Cavewriting

Disclaimer

This software is under rapid development. There are probably many many bugs. The documentation is incomplete.

Report bugs to sab@cs.brown.edu.

Overview

There are two layers at which you can author cavewriting. The easier layer is the xml layer. The harder layer is the C++ layer.

Creating a Sandbox

mkdir asgn1
cd asgn1
cp $G/src/cavewriting/programTemplate/* . 

Note that there's a period at the end of that line. Don't worry when it says "skipping directories."

make

README

View the file README.txt in your asgn1 directory.

Running

To run on the desktop --will only work from dev1, dev2, or dev3.

./run desktop

Note that says "dot slash run". To run in the cave --

./run cave

The first time you do this, it will ask you "Are you sure you want to connect?" Type yes; you will have to type yes four times. If it says Abort, Abort, Abort, Abort, well, that's just not good. Ask someone what to do.

To stop it, go to the window in which you launched it and hit control-c.

xml_description

We parse in XML, and create XML-aware nodes as we go. Right now the structure looks like this:

story
    section
        word
scene
    section

The file $G/lib/IS3D/config/cave-displays.cfg contains the description of the geometry of the cave walls used by IS3D. The cave is 8 units high, 8 units wide, and 8 units tall. The origin is at the center of the cave. So, the floor, for instance, is a 8x8 square at y=-4.0, bounded by the lines x=-4, x=+4, z=-4 and z=+4.

As you're standing in the cave facing the front wall,
positive x is to your right positive y is up positive z is behind you / negative z is in front of you

In cavewriting, you can give a section a translation, in the form

<section>
<translation>(x, y, z)</translation>
....
</section>

...so that...

<translation>(-4, 4, -4)</translation>

puts a section on the front wall.

Rotation is dealt with as two separate nodes,

<rotation-axis> and <rotation-angle>

so that

<rotation-axis>(1, 0, 0)</rotation-axis>
<rotation-angle>1.57</rotation-angle>

is rotation by 90 degrees around the x axis. (Åll angles are specified in radians.)

To change what xml file you load, edit settings-common.cfg. This file is just a list of variable names followed by whitespace followed by a value. The # character is a comment. The settings that you should edit are in the top of the file.

CW_StoryFile          test.xml

Example XML File

<story>

<title>geometry</title>

<section paused="true" visible="true">
<name>frontwall</name>
<translation>(-4, 2, -4)</translation>
<rotation-axis>(1, 0, 0)</rotation-axis>
<rotation-angle>0</rotation-angle>
<word>frontwall0</word>
<word>frontwall1</word>
</section>

<section paused="true" visible="true">
<name>leftwall</name>
<translation>(-4, 2, 4)</translation>
<rotation-axis>(0, 1, 0)</rotation-axis>
<rotation-angle>1.57</rotation-angle>
<word>left0</word>
<word>left1</word>
</section>

<section paused="true" visible="true">
<name>rightwall</name>
<translation>(4, 0, -4)</translation>
<rotation-axis>(0, 1, 0)</rotation-axis>
<rotation-angle>-1.57</rotation-angle>
<word>right0</word>
<word>right1</word>
</section>

<section paused="true" visible="true">
<name>floor</name>
<translation>(-4, -4, -3)</translation>
<rotation-axis>(1, 0, 0)</rotation-axis>
<rotation-angle>-1.57</rotation-angle>
<word>floor0</word>
<word>floor1</word>
</section>


<scene name="shorttest" start-time="0" duration="10" type="peel" peel-interval="1" peel-duration="15" peel-effect="peel">
<section-name>frontwall</section-name>
<section-name>leftwall</section-name>
<section-name>rightwall</section-name>
<section-name>floor</section-name>
</scene>
</story>

For Coders

The namespace is cavewriting. The most useful thing is probably to subclass cavewriting::Effect. Also see cavewriting::TestApp. C++ documentation is linked in to this document; just click on a class name.

For Coders

---