Saving Screen to file (gl_readscreen will be replaced/isn't docu'd)

[dave "who can do? ratmandu!" ratcliffe]

In article <9009041916.AA04157 at aero4.larc.nasa.gov> blbates at AERO4.LARC.NASA.GOV ("Brent L. Bates AAD/TAB MS361 x42854") writes:
>
>     I would like to be able to save the entire screen (or part of it)
>to a file of my own format.  It shouldn't matter what mode the windows
>are in, RGB or color map, I want the RGB values no matter what mode the
>window is in. That way if I have a window in RGB mode and one in color
>map mode I can save the entire screen as RGB values.
>     I have looked at 4Dgifts/iristools/imgtools and there is one utility
>to save the screen, that is scrsave.  Scrsave calls an undocumented
>function gl_readscreen.  What library is this routine in?  
                           ---------------------------->  /usr/lib/libgl.a

>                                                            Why isn't it
>documented?  
THE SHORT ANSWER:
-----------------
  because this is an evolving subtree of goodies that originally was created
as the ultimate freebie with no concern about it's "rigorous supportability".

THE LONG ANSWER:
-----------------
  long ago in a universe far away there was the 2000/3000 machine subtree 
of /usr/people/gifts/mextools which, once the era of 4D-ness was upon us 
was ported--a year and a half late--to /usr/people/4Dgifts/iristools.  the
original gifts/mextools was the "first world" incarnation of an SGI image 
library courtesy of one of the most inspired populants ever to grace the
 halls of SGI.  with the re-incarnation of 4Dgifts/iristools, the "second
world" was given form which was a greatly enhanced and expanded version of
the first.  however, being an ongoing evolution of functionality there 
still were "hidden/secret" incantations that hailed from the innards of 
libgl.a which, by their nature were/are not documented.  three of the four 
of these gl_ GL source code calls have been expunged as of the 3.3 release.  
the single remaining vagrant is the ubiquituous gl_readscreen.
  this was not replaced with a standard GL function call as of 3.3 because
it's "replacement" is NOT a trivial matter and closure on the remaining
ambiguities about its current form and function was not able to be 
achieved in time.  ever since 4Dgifts/iristools made its debut, support 
engineering has received an ongoing litany of confusion/frustration/concern 
about this single "jump-door" between the visible universe of the GL 
Reference Manual, and the invisible, apparently dimensionless universe of 
libgl.a.  as the one who has been responsible for 4Dgifts, i made a 
concerted effort last fall to achieve closure on this anachronism *before*
the development of the [then future] 3.3 release was frozen.  unfortunately,
i failed in my quest.  quoting a segment from one of the many e-mail 
proposal pieces i sent around the internal circuit late last year:

   - i have a personal stake in a TIMELY resolution to the issue of
     replacing gl_readscreen with a supported function that includes,
     among other things, a concise, well-defined man-page that cust's 
     can refer to for the bottom line of how such a function REALLY
     works and what they can expect it to do and not to do.  Such
     customer interest has been increasing since 4Dgifts was created
     and beyond that, with the introduction of snapshot--people want 
     to know more about this ubiquitous gl_readscreen wraith.  From
     a support issue, i have been assuring people for at least six
     months that i would see to it that gl_readscreen will be soon
     supplanted with a support function.  i don't feel as if this
     promise was unrealistic.  Hence i have become its primary advocate.

  suffice it to say that we are intimately aware of the aberration.  we are
engaged in trying to reach a consensus about how to replace gl_readscreen
with a supported/fully-documented GL function, but the various issues
pertinent to this transmorgrification are still being debated in terms of
how this call is related to other functionality still needing clarification.


>              It seems to be the only function that will do what I want,
>however there is no documentation.  Is it ok to use this function or will
>it disappear some day.  
 it *will* disappear someday

>                        It should be a normal library function, complete
>with documentation.
>     I have tried using other routines with no success.  Any suggestions?
>Most of this is aimed at SGI.

  as you have already surmised, no other function provides the kind of i-can-
grab-any-section-of-the-screen-you-want-regardless-of-it's-window's-display-
mode,-and-return-to-you-an-RGB-SGI-imagelib-image-file.  
  the gl_readscreen function implementation varies based on which machine yer
on.  in the GT[X] version it is approximately 85 lines and comprises about 5
different gl_ calls within its body.  it does ALOT of low-level ugly-gutsy 
stuff that provides you with the i-don't-care what-displaymode-yer-running 
capability.  there really is nothing you can do to "replace" gl_readscreen 
until we are successful in doing so in-house and then incorporating it into 
the next SW release.  in the meantime, the best (and i'll grant you its not 
good enuff) thing i can suggest is to know that gl_readscreen only can work 
on one scanline at a time--it's maximum length being XMAXSCREEN--and that the 
addresses of the three arrays you pass in will come back with the red, green,
and blue components of each pixel on that scanline starting at the X position
you set things to via cmov2i prior to calling gl_readscreen.  sorry for the
hassles.  this stuff has not solidified yet.  
--
                                             daveus rattus   

                                   yer friendly neighborhood ratman

                              KOYAANISQATSI

   ko.yan.nis.qatsi (from the Hopi Language)  n.  1. crazy life.  2. life
     in turmoil.  3. life out of balance.  4. life disintegrating.  
     5. a state of life that calls for another way of living.