-------------------------------------------
entry variable: $rgb -- abs filename output bitmap
-------------------------------------------
default: */rgb/tksurfer.tiff (or set by script)

The "rgb:" entry shows the current bitmap image
file name.  To write out the current buffer to
this file, use "W".  To view a previously saved
bitmap, select one from the dropdown and use "R".

This variable is usually pre-set by a script to
the following name format:

  3D:	[scannum]-[scandir]-[hemi]-[surf]-[view].tiff
  flat:	[scannum]-[scandir]-[hemi]-[patch].tiff

Session directory can be abbreviated as an
asterisk (*).  Absolute name OK, too.  Relative
name is appended to $session/rgb/.  Must confirm
overwrite, or use tcl function save_rgb directly
(doesn't ask).  Alternatively, set target rgb
directory ($named_rgbdir) and write rgb file with
tcl function: save_rgb_named <relative_name>.

To quickly see the names of already-saved
bitmaps, do a R-click on the "rgb:" label itself

The default bitmap output format is tiff (3 bytes
per pixel, lossless LZW compression, no
transparency).  To obtain an SGI rgb file, unset
$tiffoutflag by unclicking the unlabled check at
end of the rgb entry, which will update output
file suffix), or restart tksurfer from csurf with
Preferences -> Save .tiff unselected.

If $black2transparentflag is set (Preferences ->
Surf:Black->Transpar ticked), the black
background will be converted to transparent and a
4 byte per pixel tiff will be written (N.B.: some
tiff viewers ignore or mishandle tiffs with
transparency).

Offscreen rendering

The bitmap saved with "WRITE" comes from the
current onscreen window.  To obtain a bitmap that
is larger than the screen size, use offscreen
rendering.  This currently requires a tcl script.
The tcl flag, $renderoffscreen, has to be set to
1 and the window size set with "resize_window"
*before* the GL window has been opened with
"open_window" (if a window is already open, first
close it with "close_window").

Here is an example of a complete tcl script to
read in a particular surface (inflated), a
curvature data set (sulc), a complex-valued
overlay data set (polar1{_r,_i}-$hemi.w), and
then render a high resolution medial view of it
and exit:

  close_window
  resize_window 2500
  set renderoffscreen 1
  open_window
  setfile insurf ~/surf/$hemi.inflated
  read_binary_surface
  setfile curv ~/surf/$hemi.sulc
  read_binary_curv
  make_lateral_view
  set overlayflag 1
  set complexvalflag 1
  setfile val */scandir1/polar1_i-$hemi.w
  smooth_val 10
  push_val_val2
  setfile val */scandir1/polar1_r-$hemi.w
  smooth_val 10
  make_lateral_view
  rotate_brain_y 180
  redraw
  setfile rgb ~/rgb/polar1-rh-inflated-med.tiff
  save_rgb
  exit

Put these commands into a file, test.tcl,
in a functional session scripts directory.
This script can be run, either from the
command line:

  cd $FUNCTIONALS_DIR/130625MS/image/scripts
  tksurfer marty rh smoothwm -tcl test.tcl

or using "GO" (any cmdline surf OK since script
reads a specific one).  The tiff will be written
into the "rgb" subdirectory of the functional
session, and tksurfer will exit.

To render onto a flat patch instead, replace
the script lines:

  make_lateral_view
  rotate_brain_y 180

with:

  set patchname occip.patch.flat  ;# for setdefpatchview
  setfile patch ~/surf/$hemi.$patchname
  read_binary_patch
  restore    ;# tksurfer.tcl func to setup patchview

