3. Usage

You may run the server from either a file manager or the shell. The server will appear as a graphical window, and host a TCP socket at port 17702 by default. From this point, you can run the test client from a shell, and after it connects to the glAppGrapher, you can watch objects appear in the glAppGrapher. You may then use the left, right, and middle mouse buttons to navigate around the three-dimensional world.

3.1 Command-Line Parameters

3.2 Logic

The glAppGrapher contains a linked list of OpenGL and GLU-based commands. Each time you send the glAppGrapher a command to either render something or change a render property, the glAppGrapher will add your command to the linked list. Every time the glAppGrapher redraws itself because of a camera movement, a window refresh, or the act of having a command sent to it; it will clear the scene, and traverse the entire linked list for commands to execute.

For example, if you send these commands to the glAppGrapher from your code only once:

glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);

The glAppGrapher will perform this sequence of events every time it redraws:

glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);

If you used the mouse to move around the scene, and logged each command as it happened in the glAppGrapher, your log file would look something like:

glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);
glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);
glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);
glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);
glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);
glColor4f(1,0.5,0.5,0);
glVertex3f(0,0,0);

So, how does the server know you want it to call "glColor4f" and "glVertex3f"? Because in the command you pass to it, you send the name of the OpenGL function you want to call, as well as all its parameters. If any of those parameters are a pointer, you will just pass all the raw data that is pointed to. Later on when the glAppGrapher actually handles your command, it maps the name of the OpenGL function to the actual OpenGL function itself, passes in the parameters that you gave it, and calls the function. Read on for more details.

3.3 Usage in your own program

This is where the real explaining comes into play. The test client comes with source, so you can see how the communication takes place in passing commands through sockets.

The first step to establishing communication begins when the glAppGrapher is running and hosting a server. Upon starting your client program, you must use Berkeley Socket calls at the TCP layer to connect to the glAppGrapher. Once you are connected, you send commands to the glAppGrapher through your socket via binary data as shown below.

Every command the test client sends to the glAppGrapher is built in the following format:

• Message ID (4 bytes) - This may be one of the following values as defined in glappgraphermsg.h:

  GLAG_MSG_CONSOLE:    This is a zero-terminated string you want to feed to the console; as if you were there typing it in.
  GLAG_MSG_CLEAR:          The message is a command for the glAppGrapher to clear all rendered objects.
  GLAG_MSG_LOAD:           (Reserved)
  GLAG_MSG_SAVE             (Reserved)
  GLAG_MSG_AXISMODE  (Reserved)
  GLAG_MSG_FUNC            The message is a OpenGL, GLU, or other  function for the glAppGrapher to execute in the main loop, complete with parameters
  GLAG_MSG_SHUTDOWN  (Reserved)

   

Based on what the message ID is, these fields will follow the Message ID  field:

For GLAG_MSG_CONSOLE: The zero-terminated string you want to send to the console; as if you were typing it in from the console.

For GLAG_MSG_CLEAR: None

For GLAG_MSG_GL_FUNC:

• Function name (Zero-terminated string) - The name of the OpenGL function we want to call (i.e. "glEnable", "glColor4fv")

• Flags (4 bytes) - Flags for the message based on what the message ID is.

  • GLAG_CMD_IMMEDIATE:  The function will be called immediately rather than being stored in the command list. This can be used in later versions that support more than 2048 bytes per command for sending texture-related and other one-time initialization commands.

• Parameter count (4 bytes) - The number of parameters following this field. This would be the same as number of parameters in the function prototype.
• Parameters
  • Parameter size (4 bytes) - The size, in bytes, of the parameter. If the parameter is a 4-byte integer for example, you would pass in 4. Pointers are exceptions. For a pointer, the size should be the number of bytes the data being pointed to is, and the size itself must be logically OR'ed with GLAG_IS_POINTER. Examples: For the function "glEnable" this would be sizeof(GLenum). For "glColor4fv" this would be sizeof(Glfloat) * 4 logically OR'ed with GLAG_IS_POINTER.
  • Parameter (n bytes) - This is the parameter itself. It can be a GLfloat, GLint, GLenum, or in the case of where we would otherwise pass in a pointer, the actual data itself.

Please look in glappgrapherclient.cpp for details. 

You may notice that most of the messages ID's have no accompanying implementation. They have yet to be implemented in a future release.