GEM ONLINE DOCUMENTATION CHAPTER 6: FAQ
---------------------------------------

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?)

--------------------------------------------------------------------
--USING GEM--
2.1) Why doesn't GEM run?
2.2) I've got it running.  Now what?
2.3) On IRIX 5.3, why does GEM dump with an rld error?
2.4) Why can't I compile GEM on IRIX 5.3?
2.5) Why is GEM slow in general?
2.6) Why is GEM slow on IRIX?
2.7) Why is GEM slow on WinNT/Win95?
2.8) Why is GEM slow on Linux?
2.9) If I resize the window, everything looks strange.

--------------------------------------------------------------------
--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?

--------------------------------------------------------------------
--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?

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

--------------------------------------------------------------------
--OBJECT SPECIFIC--
7.1) Why doesn't <object> exist on <platform>?
7.2) Why doesn't gemtablet work?
7.3) Why doesn't gemmouse work in IRIX/Linux?
7.4) 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 (mdanks@cybermed.ucsd.edu) 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://cybermed.ucsd.edu/mdanks/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 ftp://crca-ftp.ucsd.edu/pub/msp

    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://iem.mhsg.ac.at/~geiger).
Paul Ossenbruggen (poss@xaostools.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?

	The only other set of Pd objects that I know about is a collection I wrote
called MarkEx.  You can get it at

http://cybermed.ucsd.edu/mdanks/MarkEx

It has counter, average, and a bunch of objects to deal with vectors
(very useful in GEM for color and position).

----
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, the only other site that I know about
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://iem.mhsg.ac.at/~geiger

    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?)

    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

--------------------------------------------------------------------
--USING GEM--
2.1) Why doesn't 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

Notice that the -lib flag always requires Unix styles slashes.  If you
don't see a startup message from GEM, then something went wrong.
	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.2) I've got it running.  Now what?

  Probably the first thing that you will want to do is 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 gemRedSquare.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.  gemMoveLight.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.3) 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 5.3- machine, so don't expect any
builds from me.  Upgrading to IRIX 6.2 is worth it (also, IRIX 6.5 is
right around the corner :-)

----
2.4) 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.5) 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.
    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.6) 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.7) Why is GEM slow on WinNT/Win95?

	You probably don't have hardware acceleration. If you do not have
a hardware OpenGL accelerator card, then at least get
SGI's OpenGL for Windows (http://www.opengl.org).  It is much faster than
Microsoft's OpenGL.  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.8) Why is GEM slow on Linux?

	It is because you have to use Mesa, which only runs in software. 
Mesa 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 sanctioned by the OpenGL ARB, such, it is doesn't
have the OpenGL name.  There is an acceleration package for the Voodoo
graphics card, but I don't know anything about it.

----
2.9) 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.

--------------------------------------------------------------------
--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 there.  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).

--------------------------------------------------------------------
--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.  There are probably some serious problems with this, so
if someone wants to give it a shot, let us know.

----
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?

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

--------------------------------------------------------------------
--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.3)
    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 window.

----
7.3) 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.4) 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, and it seems to assume
that you are only writing to a file or previewing into a window.  If 
anyone knows how to deal with this, please let me know.
