
3d-Desktop
----------

3d Desktop is an OpenGL program for switching virtual desktops in
a seamless 3-dimensional manner.  The default "visualization" maps
your screen onto an N-sided "carousel" which is rotated to select the
next screen.  When activated the current desktop appears to zoom out
so as to make your desktop appear to be actually in a 3d environment
with your other desktops.

The latest version of 3d-Desktop can be found at:

   http://desk3d.sourceforge.net/

Requirements
------------
  OpenGL/Mesa (Hardware acceleration is strongly recommended)
  GLX
  XF86VidMode extensions
  Imlib2
  (The -devel components are necessary for compilation)

Installation
------------

    tar zxvf 3ddesktop-x.y.z.tar.gz
    ./configure
    make
    make install

Setup
-----

    3ddesk --acquire=700

This starts the 3ddeskd server and acquires an image of each of your
virtual desktops.  It will cycle through each desktop and return to
your current.


Running
-------

    bind a key combination to "/usr/bin/3ddesk"

    press the keys and BINGO!  3D sweetness :)


This will bring you into a 3d environment where you choose your next
desktop.  If the server hasn't been started it will try to start it.
Also see "Starting the server manually" below.

Add a global keybinding ("shortcut") via the window manager to run
/usr/bin/3ddesk.  Something like C-M-s (Control-Meta/Alt-s) or
whatever won't conflict with anything else.  When you press this key
combination 3ddesk signals 3ddeskd to start up and it zooms out to
show you the "3d visualization" of your desktops.  Then you select the
screen you want to switch to by pressing ENTER.

In Gnome 1.4 with Sawfish you can add keybindings by going to the
Gnome Control Center (gnomecc) --> Sawfish --> Shortcuts --> Add -->
"Run Shell Command"

The default window manager in Redhat 8.0 is Metacity and will allow
you to bind a key combo to an arbitrary command but its a little
tricky.

Run "gconf-editor". Drill down to apps --> metacity -->
global_keybindings. Find "run_command_1" and change it to your key
such as "F12" or "<Control><Alt>S".  Then in apps --> metacity -->
keybinding_commands find "command_1" and set it to "/usr/bin/3ddesk".

Do "3ddesk --help" and "3ddeskd --help" for options.


Starting the server manually
----------------------------

The server needs to be running in the background before you can go 3D.
Just run "3ddeskd" to start it.  Give the --acquire option to acquire
cached versions of all your desktops.  It will cycle thru all your
desktops/workspaces.  3ddeskd runs at all times to reduce load time
and maintain a persistent state.  3ddesk activates the server and
gives you a fullscreen.  

You only need to start 3ddeskd once!  If you run 3ddesk and it sees
the server isn't started it will attempt to start it for you.




**NOTE** When you start 3ddesktop without --acquire you will not see
the images of your other desktops.  It can only take a snapshot of
your current desktop -- so either it must acquire them initially by
cycling through all of them or they will not show up until you move
from them using 3ddesktop.  Your other virtual desktops *will* show up
but only *after* you've been to them.

The texture for the current desktop is acquired when you start 3ddesk
so once you start 3ddesk from each virtual desktop your screens will
all show up.  They will only stay consistent if you only use 3ddesk to
switch desktops (if you don't use deskguide).  Mess around with it
you'll see how it works.



Control
-------
KEYS:
Left .................... left desktop
Right ................... right desktop
Down .................... desktop below
Up ...................... desktop above
1-9,0 ................... go to desktops 1 thru 10
Enter,Space,Escape ...... choose current desktop
     
MOUSE:
Left button ............. left desktop
Right button ............ right desktop
Middle button ........... choose current desktop (column)
Wheel down .............. left desktop
Wheel up ................ right desktop



Configuration File
------------------

The configuration file is an optional file in ~/.3ddesktop/ called
3ddesktop.conf.  The example one provided is mostly self documenting.
It can be found in the tarfile or is installed into /etc.  If you want
to edit your own then copy from /etc to ~/.3ddesktop/.

It's divided into sections called "views" which you specify on the
3ddesk command line with the --view option.  They are for tailoring
the look mostly.  The options for the default view can be specified
with a view of name "default".

If you edit stuff in 3ddesktop.conf you should not need to restart the
server.  If you don't see your change check your spelling or try
3ddesk --reload.


Window Manager Support
----------------------

All the window managers seem to have different terminology for what
they call virtual desktops/viewports/workspaces. 

GNOME:

In general you can have a grid of "areas" or "viewports"made up of
some number of rows by some number of columns.  Then you can have
"workspaces" which are some number of layers of these grids.  So if
you have a 2x2 grid of areas and 2 workspaces you have 8 virtual
desktops (4 areas per workspace times 2 workspaces).

Right now 3ddesktop will display each row one after the other linearly
for most "modes" except for "linear" which ironically is not really
linear any more (more like planar or 2d).

3ddesktop can be told to use the layered workspaces instead of the
grid of areas with the command line option --workspaces.  You can use
3ddesktop to switch between areas or you can use it to switch between
workspaces but not both (not yet!).  Things get weird if you use both.

3ddesktop will automagically use the --workspaces mode if it sees
that's all you have.

This was developed using Redhat 7.1 and 7.2 on GNOME 1.4 using sawfish.

GNOME 2:

Support should be there, use the --ewmh or --gnome2 flag to 3ddeskd or
use "ewmh" or "gnome2" in the config file.  Thanks to Olivier Samyn
for the info and testing.  GNOME 2 uses the EWMH standard (just like
KDE 3).

KDE 2:

KDE is supported with the --kde2 argument to 3ddeskd or kde2 option in
the config file.  Window managers that are "compatible" with KDE
should work with this option!

KDE 3:

KDE 3.x uses the same standard as GNOME 2 called EWMH.  This is
enabled with the --ewmh option

Redhat 8.0 uses GNOME 2 and/or KDE 3 so use "ewmh".

Enlightenment:

In Enlightenment, the workspaces are configured in the "Multiple
Desktop Settings" dialog as layered virtual desktops.  You configure
the areas as a grid in the "Virtual Desktop Settings" dialog.

It is recommended you turn off the "Slide desktops around when
changing" option in Special FX Settings.  This has an unnatural effect
when using 3ddesktop (thanks Nick!).

WindowMaker:

WindowMaker only supports workspaces and calls them by the same name.
To my knowledge you can't do any kind of "area" or grid setup.  Use
the --workspaces option (should automagically detect though).

   ** Make sure WindowMaker is compiled with the --enable-gnome
      switch if you are compiling it.

Sawfish:

In Sawfish you go to the configuration section called "Workspaces" and
the grid size of the areas is specified with the columns and rows
values.

FVWM2: Works fine.
fluxbox: Works fine.



Other random comments
---------------------

This is my first OpenGL program so I'm sure there are lots of things
that aren't perfect or need work.  I'm open to any kind of feedback
positive or otherwise.  Please let me know your thoughts by emailing 
bard at systemtoolbox.com

The desktop switching is done with code originally based off of STPH
by Rob Hodges.  See http://stph.sourceforge.net/ for more info.
Thanks Rob!  Support for all the differents methods of desktop
switching has been hacked in.  Some intelligence for using workspaces
instead has been built in and I hope to put more intelligence in so
you don't have to specify an argument.

For some fun try a command line option like: 
   3ddesk --mode=linear --nozoom

Or the example views like:
   3ddesk --view=slide
   3ddesk --view=linearzip
   etc.

Do 3ddesk --help for more command line options.

There are several things that I know need work.  (See the TODO file)

I believe I've solved the load time by using Imlib2.  The biggest
bottleneck to starting was not the actual capture of the screenshot
but rather the scaling of the image to a size that is a power of two
(required for textures).

Anyway Imlib2 has wicked fast scaling so things are much faster now.
I've also switched to a daemon architecture which won't require
reloading of every texture every time (the opengl context stays
active).  *Please* let me know if this is not working because I do
some funny things with X and glX to make this work.

I switched from using GLUT to using GLX and XF86VidMode extensions to
fix some fullscreen problems.  The problem was that with
glutFullScreen (and game mode) any gnome panels that were "autohide"
would show up on top of 3ddesktop.  Additionally the window
decorations in enlightenment were staying visible.  So by using GLX
and XF86VidMode both these problems were solved.  In addition I was
able to hide the mouse pointer.  If somebody can show me how to do
this in GLUT I'd use glut.


Aug 2002: 
I rewrote and rearranged a lot of stuff to fix some major roadblocks
to progress.  There is a nifty conf file now.  I'm still having
trouble getting the background image capture to work well enough.
Also having trouble changing the transparancy of the faces.  I can
make them transparent but can't adjust the level of transparency.  Is
this because the textures are RGB instead of RGBA?  (Hit 'b' to see
transparency)


*Please* let me know if anything isn't working otherwise I won't know
to fix it :)

Brad Wasson
bard at systemtoolbox.com





Contributors
------------
Thomas Clausen
Nathan Grennan
Bryan Smith
Andy Bakun
Pedro Caria
Artur Frysiak
Antonio Larrosa
Pawel Golaszewski 
Olivier Samyn
Marcelo Magallon
Tilmann Bitterberg

Much thanks! (and let me know if I missed ya!)
