## GEM FAQ

Last updated for GEM version 0.83

* : new question
+ : changed question

## QUESTIONS

GENERAL
1.1) What is GEM?
1.2) What is Pd?
1.3) What platforms do GEM and Pd run on?
1.4) How do I install GEM and Pd on IRIX?
1.5) How do I install GEM and Pd on WinNT?
1.6) Are there any other Pd libraries?
1.7) What is a good intro to OpenGL?
1.8) Are there any web sites for Pd or GEM?
1.9) What libraries does GEM use? (aka: Who does Mark want to thank?)
1.10) Are there any restrictions on GEM?
1.11) How do I use GEM in a performance?

USING GEM
2.1) How do I (???)
2.2) How do I make GEM run?
2.3) Why doesn't GEM run?
2.4) I've got it running. Now what?
2.5) On IRIX 5.3, why does GEM dump with an rld error?
2.6) Why can't I compile GEM on IRIX 5.3?
2.7) Why is GEM slow in general?
2.8) Why is GEM slow on IRIX?
+2.9) Why is GEM slow on WinNT/Win95?
+2.10) Why is GEM slow on Linux?
2.11) If I resize the window, everything looks strange.
2.12) Can GEM run on a 3Dfx Voodoo card?
2.13) Will GEM support hardware transform and lighting (T&L) ?
2.14) I get an error "GEM needs Truecolor visual support".

VIEWING OBJECTS
3.1) Why does everything seem dim?
3.2) Why does everything seem dark?

TEXTURE MAPPING
4.1) My image doesn't appear. What is going on?
4.2) My image looks strange. What is going on?
4.3) Why does GEM say that it can't handle a gray image?
4.4) What image formats can GEM handle?
*4.5) Why is pix_draw so slow?

WORKING WITH PD
+5.1) Why do I get clicks in the audio?
5.2) How do I get audio data to GEM?
5.3) Why can't GEM find an image/model file?
5.4) How can I optimize my patches?

WRITING NEW GEM OBJECTS
6.1) How do I write a new GEM object?
6.2) What are the default OpenGL states?

OBJECT SPECIFIC
7.1) Why doesn't <object> exist on <platform>?
7.2) Why doesn't gemtablet work?
7.3) I don't want GEM to take over my tablet. How do I stop it?
7.4) Why doesn't gemmouse work in IRIX/Linux?
7.5) Why doesn't gemorb work?
7.6) What is wrong with pix_video in WinNT?

## ANSWERS

GENERAL
1.1) What is GEM?

GEM is the Graphics Environment for Multimedia. It was written by Mark Danks (mark@danks.org) to generate real-time computer graphics, especially for audio-visual compositions. It originally ran under FTS/Max (which is why you might see some papers reference it), but all new development is under Pd.

You can get GEM at http://www.danks.org/mark/GEM

GEM is sponsored by a grant from Intel (http://www.intel.com)

----
1.2) What is Pd?

Pd is a real-time environment for audio and MIDI. It was written by Miller Puckette (msp@ucsd.edu), who created FTS/Max when he was at IRCAM. Basically, Pd can be seen as the next generation of real-time visual programming languages. GEM runs inside of the Pd environment.

You can get Pd at http://www.crca.ucsd.edu/~msp/software.html

Pd is sponsored by a grant from Intel (http://www.intel.com)

----
1.3) What platforms do GEM and Pd run on?

GEM and Pd run on SGI Irix 6.2 or greater and Windows NT 4.0. Miller and I have reports that GEM and Pd also run on Windows 95, but we have no way to test or support this. Guenter Geiger (geiger@iem.mhsg.ac.at) has done a port of GEM and Pd to Linux http://gige.epy.co.at). Paul Ossenbruggen (possenbruggen@2bridge.com) is currently working on a Macintosh port.

----
1.4) How do I install GEM and Pd on IRIX?

See the readme for installing Pd.

GEM should be at

pd/gem

If you run GEM.INSTALL.sh, then all of the example files and documention should be put in the correct locations.

----
1.5) How do I install GEM and Pd on WinNT?

See the readme for installing Pd.

unzip GEM so that it is at

pd\gem

If you run GEM.INSTALL.bat, then all of the example files and documentation should be put in the correct locations.

----
1.6) Are there any other Pd libraries?

There used to be a collection of externals called MarkEx. These have been folded into GEM.

Please let me know if you have a library for Pd or GEM.

----
1.7) What is a good intro to OpenGL?

The best book is the OpenGL Programming Manual by Mason and Woo. This is also called the "Red Book". If you search the web, there are many sites on OpenGL. A good starting point is http://www.opengl.org. Also, Mark Kilgard (who used to work for SGI) has a wonderful site with lots of links (http://reality.sgi.com/mjk)

----
1.8) Are there any web sites for Pd or GEM?

Except for the ones noted above, there is the Japanese installation page at
http://www.rinc.or.jp/~kotobuki/gem/index.htm

There is a Pd mailing list. Subscription info is on Guenter's site http://gige.epy.co.at/

If anyone makes or knows of other sites, please let me know. I will include them here.

----
1.9) What libraries does GEM use? (aka: Who does Mark want to thank?)

All copyrights and license info can be found in
GEM.LICENSE.TERMS
Thanks to Sam Leffner for libTiff, the TIFF image loader.
sam@engr.sgi.com
ftp://ftp.sgi.com/graphics/tiff/
Thanks to Masayuki Matsumoto for fstimage for OpenGL, the SGI
image loader.
matumot@dst.nk-exa.co.jp
Thanks to the Independent JPEG Group for libjpeg, the JPEG image loader.
jpeg-info@uunet.uu.net
ftp://ftp.simtel.net/pub/simtelnet/msdos/graphics/
Thanks to Nate Robbins for td, the Alias/Wavefront model file loader.
ndr@pobox.com
http://www.pobox.com/~ndr
Thanks to Stephane Rehel for GLTT, the OpenGL TrueType render.
rehel@worldnet.fr
http://home.worldnet.fr/~rehel/gltt/gltt.html
Thanks to David Turner, Robert Wilhelm, and Werner Lemberg for
Freetype, a TrueType font rendering engine.
turner@enst.fr
robert@physiol.med.tu-muenchen.de
a7971428@unet.univie.ac.at
http://www.physiol.med.tu-muenchen.de/~robert/freetype.html
Thanks to the MPEG Software Simulation Group, for libmpeg, the
MPEG-2 Encoder/Decoder
mssg@mpeg.org
http://www.mpeg.org/MSSG/
Thanks to LCS/Telegraphics for Wintab, the Windows tablet library.
wintab@pointing.com
Thanks to David McAllister for the Particle System library.
davemc@cs.unc.edu
http://www.cs.unc.edu/~davemc/Particle/
Thanks to John Stone for the Space Orb library, libOrb
j.stone@acm.org
http://www.umr.edu/~johns/projects/liborb/

----
1.10) Are there any restrictions on GEM?

GEM is under the Gnu Public License. This basically means that it will always be free software. Check out http://www.gnu.org for more information and read the full license in GnuGPL.LICENSE in the GEM release.

----
1.11) How do I use GEM in a performance?

This is a constant problem, because there is no consistent way to display video on any platform. Also, you usually do not want to send the entire screen, but only the GEM window. It is also useful to be able to edit/control the Pd patch window while the patch is actually running.

On SGIs, the best way is to get a video out option. On the SGI O2, Impact, and Onyx (I have used all of these), there is a simple connector or breakout box to do video. If you run the video out program, then you will get a rectangle on your screen which shows what is being sent out the video connector. Make your GEM window a little larger than 640x480 and center it in the rectangle. You can now project this with a standard video projector.

On PCs it is a bit harder. I have a Canopus Voodoo2 card which has a video and s-video output on it. As described in question 2.10, you can get a Voodoo to work with GEM. If any one else has a better solution, please let me know. The nVidia Riva TNTs require that you output the full screen, so this is not a very good option. You can use a video scan convertor. Some of them only display a part of the scene, which is exactly what you want.

If you are doing audio with graphics, the only solution to prevent clicking (question 5.1) is to run computer and have them communicate with netsend/netreceive. We are working on making Pd/GEM multi-processor friendly, so if you have a multi-processor system, you can run everything on one machine eventually.

USING GEM
2.1) How do I (???)

Many of the general usage questions are probably answered in the manual or release notes. The pd mailing list is also a good place to find answers as well.

2.2) How do I make GEM run?

GEM is not an executable. It requires Pd to work and is loaded in at run time. For example, I have an alias on the SGI which does

/usr/people/mdanks/pd/bin/pd -lib /usr/people/mdanks/pd/gem/Gem

and on WinNT

\pdDir\pd\bin\pd -lib /pdDir/pd/gem/Gem

If you don't see a startup message from GEM, then something went wrong.

Most people use use the command shell to start Pd. It is difficult to configure Pd to run from double-clicking on the icon.

Also, you might need to add pd/bin to your PATH environment variable.

----
2.3) Why doesn't GEM run?

Notice that the -lib flag always requires Unix styles slashes. This is the case even on Windows.

You may also want to use the -nosound flag. For instance, my PC has problems using audio (it leaks memory), so I just turn off the audio part of Pd. However, other people can't get GEM to work if the -nosound is used (on Win95). You can also try the -dac or -adc flags (for digital-analog-conversion only and analog-digital-conversion only).

----
2.4) I've got it running. Now what?

Try out the manual. It will step you through the basics.
You will also want to look at the example files. Assuming that everything is installed correctly, you can get to the examples by going to the Help menu in Pd and selecting examples. A bunch of the patches should start with gem<something>. The best one is gem_basic/gem1.redSquare.pd It puts a red square up on the screen and allows you to rotate it. gemImage.pd shows how to load in a TIFF file. gem_lighting/gem3.moveSpheres.pd moves two spheres around the screen. Try the other ones.
Most of the GEM objects have test patches which give some information about the various controls for the object.

----
2.5) On IRIX 5.3, why does GEM dump with an rld error?

GEM only works under IRIX 6.2+. The rld error is probably something about not having glBindTextureEXT (or something). OpenGL 1.0 has some extensions to speed up texture mapping (which are an integral part of OpenGL 1.1). However, these don't exist on IRIX 5.3. If you recompile GEM (see the next question), things should work fine.
I don't have access to an IRIX machine, so don't expect any builds from me. Upgrading to IRIX 6.2+ is worth it.

----
2.6) Why can't I compile GEM on IRIX 5.3?

There was probably an error saying that the compiler couldn't find the file "dmedia/vl_vino.h" in pix_videoSGI.cpp. IRIX 6.2+ adds new functionality to the media libraries which makes life much easier. You cannot compile pix_video or pix_indycam as is under 5.3. You can remove them from the Pix/Makefile and from the linker part of the global Makefile. You will also need to recompile the Td and Tiff libraries.

There shouldn't be any problems doing this. I haven't tried any of this, so if it works for someone, please let me know.

----
2.7) Why is GEM slow in general?

Examine what you are doing. If you are constantly changing textures, then this is probably your problem. If you have models with a million triangles, then this is probably the problem. Compare what you are doing with realistic specs on your system. Some systems slow down when they have to draw very large polygons (slow fill rate).
You can also turn on profiling to see how long it takes to render a frame. Send a profile message to the gemwin object. The number that is printed is the number of milliseconds one frame takes to render. 50 milliseconds is 20 frames per second. 'profile 2' is good if you want to see how long the image processing is taking.
profile 0 - turn off profiling
profile 1 - turn on profiling
profile 2 - turn on profiling and don't cache pixes

----
2.8) Why is GEM slow on IRIX?

If you are having major slowdowns, then please let me know. I have gotten very good performance on most machines (Indy, O2, Impact, Onyx2).

----
2.9) Why is GEM slow on WinNT/Win95?

You probably don't have hardware acceleration. You can use software rendering, but it basically useless except for extremely basic patches. You can get a good graphics accelerator for really cheap these days. I recommend a card based on nVidia's chipsets, such as the TNT2 or GeForce256, but there are other companies such as 3dfx and Matrox. Make sure that you are running the latest drivers for your card. The basic drivers that come with the cards are usually very bad.
Also, PCs don't deal with lots of texture maps very well (they are bus limited, at least until AGP), so if you are trying to use lots of constantly changing texture maps (especially with pix_multiimage), that will cause problems.

----
2.10) Why is GEM slow on Linux?

It is because you have to use Mesa, which might be running iin software. Mesa (http://www.mesa.org) is an awesome package by Brian Paul (brianp@avid.com) which "emulates" OpenGL. Basically, it is a fully compliant OpenGL package, but it isn't officially sanctioned by the OpenGL ARB, such, it is doesn't have the OpenGL name. There is an acceleration package for the many graphics card, but I don't know anything about it.
nVidia is being very supportive of Linux. Their TNT2 and GeForce256 cards are supposed to work under Linux.

----
2.11) If I resize the window, everything looks strange.

GEM doesn't trap resize events in IRIX or Linux (this is not a problem in WinNT). This means that OpenGL doesn't have the correct information to render properly. If you want to resize the window, send a 'dimen x y' message to gemwin before you create the window.

----
2.12) Can GEM run on a 3Dfx Voodoo card?

I have a Voodoo2 card, which runs fine under WinNT. I use the OpenGL beta driver from 3Dfx at work all the time without any problems and, except that the Voodoo takes over the full screen, it seems to work fine. You will need to download the OpenGL Beta driver from 3Dfx's web site at http://www.3dfx.com and put the OpenGL32.dll into the same directory as pd.exe (NOT gem.dll). Debugging patches is much easier if you have two monitors, one for the 3-D card and one for the 2-D card.

IMPORTANT: You MUST set the environment variable

GEM_SINGLE_CONTEXT = 1

to make the Voodoo card work. It will make a window 640x480 (which is the correct size for TV video out on my Canopus V2 card). On WinNT, right click "My Computer" and go to "Properties". On the "Environment" tab, you need to add the variable "GEM_SINGLE_CONTEXT" with a value of 1.
Resizing the GEM window with a Voodoo card is not a great idea. The Voodoo card can only display certain window sizes and will clip the graphics.

For the tech heads in the audience...I create an OpenGL context at startup and never actually display its associated window. This means that GEM objects can create display lists, call OpenGL commands, etc. in their constructors, even if no window is actually being displayed. However, with the Voodoo card, there can only be one OpenGL context. So, instead of creating one context and just holding onto it in the background, I create the normal GEM window and associate the OpenGL context with it...and the user can never destroy or close that window.

----
2.13) Will GEM support hardware transform and lighting (T & L)?

Absolutely! Unlike some other APIs, OpenGL will automatically use hardware accelerated transform and lighting if the card has it. GEM should get great performance from cards like nVidia's GeForce256.

2.14) I get an error "GEM needs Truecolor visual support".

This error means that your X display is running with paletted colors, which is the result of limited color depth. If you start the X display with

startx -- -bpp 16

or some higher number, then it should work fine. 32-bit color is the best.

VIEWING OBJECTS
3.1) Why does everything seem dim?

You probably turned on lighting but don't have any lights in the world. Either add a light with world_light or light or turn lighting off by sending a message 'lighting 0' to the gemwin. You can also send a reset message to gemwin to set it back to the startup state (which doesn't have any lighting).

----
3.2) Why does everything seem dark?

See question 3.1.
If you have a camera in your patch, you may not be pointing in the correct direction. You also might have translated everything outside of the current viewport.
Also, if you have been using single buffering ('buffer 1' message to gemwin), then you might still be in that mode. Either send a 'buffer 2' message or a 'reset' message to gemwin. Then, destroy and create your window.

TEXTURE MAPPING
4.1) My image doesn't appear. What is going on?

There are a few requirements which OpenGL (and such GEM) put on images. For an image to be texture mapped, it must be a power of 2 in both height and width. If it isn't, then you will just get the polygon without any texture mapping. If you don't/can't convert the image beforehand, then the pix_resize object will automatically resize the image to the next power of two in each dimension (this is an expensive operation though).

Also, make sure that GEM can find your image (ie, that the path name is correct).

----
4.2) My image looks strange. What is going on?

GEM supports gray8, RGB, and RGBA images. If it sees that the number of bits per channel and the number of channels is something that it should be able to handle, it tries to load the raw data. If you have compressed or stored the pixel data in some "strange" format, then GEM will probably not read the information correctly.
Also, if it is an RGBA image, then make sure that the alpha channel is something useful (this only matters if you are using the alpha channel, like in the alpha object or pix_mask).

----
4.3) Why does GEM say that it can't handle a gray image?

This error message occurs whenever a pix object receives a gray8 image and the implementor hasn't provided a way to deal with that format of image. The only way around this right now is to change the format of the image in some other program (like Photoshop or with imgcopy) or harass whoever made the object to add the functionality.

----
4.4) What image formats can GEM handle?

GEM can read in TIFF, JPEG, and SGI images. These can be in any color format. Gray scale images are loaded in as gray scale (ie, one byte per pixel). Everything else is loaded in or converted to an RGBA image (ie, four bytes per pixel). If there is an alpha channel, then it will be respected. Otherwise, the alpha channel will be set to fully opaque (alpha == 255).

----
4.5) Why is pix_draw so slow?

pix_draw is almost never hardware accelerated on PCs graphics accelerator. This means that it runs extremely slowly. Always use pix_texture, even if you are just displaying an image.

WORKING WITH PD
5.1) Why do I get clicks in the audio?

If you are getting a constant stream of clicks in your audio, then it is probably because you are trying to do graphics and audio in the same process. Rendering a graphics frame usually takes longer than the size of the audio buffer, which is why you get clicks (the clicks are usually at 20Hz...the typical frame rate).
One way around this is to use two computers, one for graphics and one for audio. If you have enough processing power (or dual processors), then you can run two versions of Pd, one for graphics and one for audio. Just use netsend and netreceive to have the two versions of Pd talk to each other.

----
5.2) How do I get audio data to GEM?

The only way to get raw audio values right now is to use snapshot~. Just set up a metro which bangs snapshot~ and use the floating point value. If you want "musical" information, then use objects such as env~.

----
5.3) Why can't GEM find an image/model file?

This means that GEM can't locate the file. If you use an absolute path (with / for instance), then GEM will look there. Otherwise, GEM will look in the directory of where the patch is. This means that different patches (which are all open at once) can be looking in different places for the file. Currently, pd/GEM doesn't have a user-specified search path yet.

Check the following:

1) Does the file exist?
2) Did you make a typo in the filename?
3) Is the file in the directory with the patch?

----
5.4) How can I optimize my patches?

One of the biggest performance hits is having UI elements in your patch which have to be updated. The biggest performance hog is the number box. While the number box is great for debugging, make sure that they are all gone from your "release" patch. If you run a performance meter, you will see that whenever Tcl/Tk has to update the user interface, it sucks the entire processor. Another examples of this is when you move a lot of objects at once, everything jerks and slides across the screen. There are probably ways to improve this...
Another problem is doing unneccessary calculations. When you are throwing lots of numbers around, especially packing/unpacking, doing vector math, etc., they add up. If the calculations are going unused (for instance, that part of the patch is turned off), then do not trigger the math objects. Use spigot or gate and block the events early. This is especially important with objects that send a lot of numbers, like ~ objects or line/tripleLine.

WRITING NEW GEM OBJECTS
6.1) How do I write a new GEM object?

For the time being, you have to look at the code. It is fairly well documented and straight forward (if you know C++ and OOP). Start with an object which is similar to what you want and derive a new class. The biggest issue right now is how to load in GEM as a DSO/DLL. For SGIs, you will need to setenv LD_LIBRARY_PATH. On NT, you will need to have your path include the directory with GEM.

----
6.2) What are the default OpenGL states?

GemMan (and by association, gemwin) disables alpha testing, alpha blending, culling, and lighting. Lighting defaults to two sided, with GL_COLOR_MATERIAL enabled. The viewport is set to

float xDivy = (float)m_width / (float)m_height;
glMatrixMode(GL_PROJECTION);
glLoadIdentity();
glFrustum(-xDivy, xDivy, -1.0, 1.0, 1.0, 20.0);
gluLookAt(0.0, 0.0, 4.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0);
glMatrixMode(GL_MODELVIEW);
glViewport(0, 0, m_width, m_height);

which gives a range of about -4 to 4 in X and Y at the origin. This is a small range, but changing it now would break a lot of patches.

The specific functions to look at are:

GemMan::windowInit()
GemMan::resetValues()
gemhead::renderGL()

OBJECT SPECIFIC
7.1) Why doesn't <object> exist on <platform>?

Usually, this is because I don't have the resources to get the object running on that platform. If an object that you want doesn't exist on your platform, then ask for it! However, if it is tied to hardware, then it is much less likely that I will be able to do anything about it (unless someone donates the hardware to me...)

----
7.2) Why doesn't gemtablet work?

gemtablet only works on WinNT. I don't have drivers for IRIX or Linux (also, see question 7.4)
If GEM can find the tablet, then it will print a message at window creation time. If you don't see a message, then GEM doesn't think that you have a tablet.
The tablet is mapped to the size of the GEM graphics window.

---
7.3) I don't want GEM to take over my tablet. How do I stop it?

Set the environment variable

GEM_NO_TABLET = 1

----
7.4) Why doesn't gemmouse work in IRIX/Linux?

Basically, I don't have physical access to an SGI or Linux machine. This makes it hard to do some of the OS specific work. It should be straightforward to do the event handling, so if someone gets it working, I would love to include it (and give you credit). All you have to do is call the correct event functions from GemEvent.h and everything should just start to work (ie, gemmouse doesn't have any OS specific code in it).

----
7.5) Why doesn't gemorb work?

You need to make sure that your SpaceOrb is hooked up correctly. I am using a library which isn't supported by SpaceTec so there can be problems, although I have not had any.
<RANT> When will companies wake up and actually provide drivers and support for their products under WinNT? </RANT>

----
7.6) What is wrong with pix_video in WinNT?

I haven't completely figured out how to get access to the video stream in WinNT. I'm using Video for Windows with a Connectix QuickCam, as well as an Intel Video Capture Card, and it seems to assume that you are only writing to a file or previewing into a window. Windows tries to take over the system and doesn't really provide any stable hooks (unlike IRIX). If anyone knows how to deal with this, please let me know.

[return]