HowToC:GetStarted

From S2PLOT

Revision as of 05:26, 30 October 2007

Getting started

An S2PLOT program typically has four separate parts:

1. Commands to open S2PLOT display and set-up the environment
2. Commands to prepare static geometry, which is generated once and then drawn on all future screen refreshes
3. Commands to prepare dynamic geometry (ie. callbacks), which are update on every screen refresh
4. A command to hand over control to the OpenGL GLUT event loop, which controls interactivity such as mouse and keyboard controls

To begin with, we will just consider steps 1 and 4.

First example

Copy and paste the following code, and save the file as s2example.c

#include <stdio.h>
#include <stdlib.h>
#include "s2plot.h"

int main(int argc, char *argv[])
{
   float xmin = -1, xmax = +1;          /* X data range */
   float ymin = -1, ymax = +1;          /* Y data range */
   float zmin = -1, zmax = +1;          /* Z data range */

   s2opend("/?",argc,argv);             /* Which S2PLOT device to open? */
   s2swin(xmin, xmax, ymin, ymax, zmin, zmax);  /* Set the display coordinates */

   s2show(1);                           /* Hand over to the display */

   return 1;
}

Compile using: cbuild.csh s2example<tt> and then run by typing <tt>s2example at the command prompt.

You will be prompted for a device type - for the moment, just press return to choose the default for your system.

A black screen should appear - not very exciting, but you have successfully started up the S2PLOT display and handed control to GLUT.

Drawing a bounding box

Next, we should start adding some static geometry.

Add the following line below the s2swin command:

s2box("BCDE",0,0,"BCDE",0,0,"BCDE",0,0);     /* Draw a coordinate box */

Save, compile with cbuild.csh and run again. This time, you should see a white box representing the coordinate system.

Testing S2PLOT interaction

You can now begin to test the interactive aspects of S2PLOT:

• Press and hold the left mouse button and move the mouse to control rotation.
• Press and hole the middle or right mouse buttons to see what affect they have.
• Press +/- to move the camera towards/away from the centre of the box.
• Press the a key to toggle autospin

For full details on interaction, see here.

Labelling the coordinates

Add the following code under the s2box command in s2example.c

s2lab("X-axis","Y-axis","Z-axis","Adding some labels");

This will create labels for the x, y and z axes, plus an overall label for the plot. If you do not want a particular axis label to be visible, you can use "".

Save, compile and run.

Hmm...the axis labels don't look too good, do they? To fix this, we need to add some additional formatting paramters to the s2box command. For each of the x, y and z axes, you need to specify a character string of option flags selected from:

• B = draw front bottom (-Y,-Z) edge
• C = draw front top (-Y,+Z) edge
• D = draw back bottom (+Y,-Z) edge
• E = draw back top (+Y,+Z) edge
• T = draw major tick marks
• S = draw minor tick marks [not yet implemented]
• M = numeric labels in conventional location/s
• N = numeric labels in non-conventional location/s
• O = draw labels on an opaque panel so they are never seen in reverse - this is always done if both M and N options are requested
• Q = make panel larger to fit axis titles drawn by s2lab function
• G = draw grid lines at major tick intervals
• L = written label is 10^(coordval), ie. logarithmic labels
• 1 = force decimal labels (this is default: redundant option)
• 2 = force exponential (scientific notation) labels

Note that the exact meaning of the B,C,D and E options depends on whether you are specifying the x, y or z axis. The ordering of the options within the option string does not matter.

As a demonstration of how to fix the labelling, replace the s2box line with:

s2box("BCDETMNOQ",0,0,"BCDETMNOQ",0,0,"BCDETMNOQ",0,0);

This will draw "panels" over which the axis labels are written. Save, compile and run - that looks much better!

Experiment for yourself

You should now be ready to experiment with changing the world coordinates (ie. the numbers that were given as inputs to s2swin), and the option string for s2box.

Function Overview

For more information on the functions we have introduced so far, see:

• s2opend
• s2swin
• s2box
• s2lab
• s2show

Common Problems

S2PLOT will not display any geometry if you do not include the s2show command. If any S2PLOT commands are given prior to the s2opend command, your code should still compile, but will probably end with the dreaded segmentation fault when you try to run it.

Test code: s2example.c

This is the full test code for this initial S2PLOT example.

#include <stdio.h>
#include <stdlib.h>
#include "s2plot.h"

int main(int argc, char *argv[])
{
   float xmin = -1, xmax = +1;          /* X data range */
   float ymin = -1, ymax = +1;          /* Y data range */
   float zmin = -1, zmax = +1;          /* Z data range */

   s2opend("/?",argc,argv);             /* Which S2PLOT device to open? */
   s2swin(xmin, xmax, ymin, ymax, zmin, zmax);  /* Set the display coordinates */

   s2box("BCDETMNOQ",0,0,"BCDETMNOQ",0,0,"BCDETMNOQ",0,0);
   s2lab("X-axis","Y-axis","Z-axis","Adding some labels");
   s2show(1);                           /* Hand over to the display */

   return 1;
}

Where to Next?

• Back to S2PLOT How To...
• Drawing points