;+
; NAME:
;   CCG_OPENDEV
;
; PURPOSE:
;   Creates a LANDSCAPE or PORTRAIT graphics file according to
;   the passed user selection.  Procedure accounts
;   for color capabilities of selected graphics option.
;
;   This procedure loads a default CCG colormap.  Users may
;   pass a file describing an alternative colormap or may
;   overwrite the default colormap following the call to
;   CCG_OPENDEV.  The IDL routine 'CCG_EX_COLOR' provides a
;   table of colors from the default color map.
;
;   This procedure is intended to be used with CCG_CLOSEDEV.
;
; CATEGORY:
;   Graphics.
;
; CALLING SEQUENCE:
;   CCG_OPENDEV,dev=dev,pen=pen,pcolor=pcolor,win=win,saveas=file
;   CCG_OPENDEV,dev=dev,pen=pen,portrait=1
;
; INPUTS:
;   dev:  Specifies the requested graphics option.
;     Current options are:
;
;     *** SAVED AS GRAPHICS FILES ***
;
;   ps:     a b/w POSTSCRIPT file
;   psc:   a color POSTSCRIPT DEVICE file
;   eps:   an ENCAPSULATED POSTSCRIPT file
;   png:   a PNG (Portable Network Graphics) file
;
;   NOTE: When a device from the above list is
;     selected, the file is saved as 'idl.[dev]'
;     in the   users HOME directory unless an alternate
;     destination has been specified using the
;     'saveas' keyword.
;
;     *** SENT TO SPECIFIC GRAPHICS DEVICES ***
;
;   lj5:   a b/w POSTSCRIPT file sent to HP LJ5 (2D701)
;   lj5_s:       a b/w POSTSCRIPT file sent to HP LJ5 (2D701, simplex)
;   optra:       a b/w POSTSCRIPT file sent to LM OPTRA (3D409)
;   optra_s:  a b/w POSTSCRIPT file sent to LM OPTRA (3D409, simplex)
;   aerolj:     a b/w POSTSCRIPT file sent to HP8000 (3D401)
;   aerolj_s: a b/w POSTSCRIPT file sent to HP8000 (3D401, simplex)
;   canon:       a b/w POSTSCRIPT file sent to CI550 (3D409)
;   canon_s:  a b/w POSTSCRIPT file sent to CI550 (3D409, simplex)
;   culj4000: a b/w POSTSCRIPT file sent to HP4000 (CU/INSTAAR)
;   o3lj_s:     a b/w POSTSCRIPT file sent to HP8000 (3D503, simplex)
;   o3lj:     a b/w POSTSCRIPT file sent to HP8000 (3D503)
;   o3lj_s:     a b/w POSTSCRIPT file sent to HP8000 (3D503, simplex)
;   lj8000_1: a b/w POSTSCRIPT file sent to HP8000 (3D409)
;   lj8000_2: a b/w POSTSCRIPT file sent to HP8000 (3D409)
;   lj8000_3d:    a b/w POSTSCRIPT file sent to either HP8000 (3D409)
;   lj8000_3d_s:  a b/w POSTSCRIPT file sent to either HP8000 (3D409, simplex)
;   lj8000_3: a b/w POSTSCRIPT file sent to HP8000 (2D701)
;   lj8000_4: a b/w POSTSCRIPT file sent to HP8000 (2D701)
;   lj8000_2d:    a b/w POSTSCRIPT file sent to either HP8000 (2D701)
;   lj8000_2d_s:  a b/w POSTSCRIPT file sent to either HP8000 (2D701, simplex)
;
;   phaser:     a color POSTSCRIPT file sent to TK PHASER 550 (3D409)
;   phasert:  a color POSTSCRIPT file sent to TK PHASER 550 (3D409, transparency)
;   phaser840:    a color POSTSCRIPT file sent to TK PHASER 840 (3D409)
;   phaser840_s:  a color POSTSCRIPT file sent to TK PHASER 840 (3D409, simplex)
;   phaser840t:   a color POSTSCRIPT file sent to TK PHASER 840 (3D409, transparency)
;   phaser850:    a color POSTSCRIPT file sent to TK PHASER 850 (2D701)
;   phaser850_s:  a color POSTSCRIPT file sent to TK PHASER 850 (2D701, simplex)
;   phaser850t:   a color POSTSCRIPT file sent to TK PHASER 850 (2D701,transparency)
;   culj5:       a color POSTSCRIPT file sent to HP5M (CU/INSTAAR)
;   hp4600:     a color POSTSCRIPT file sent to HP4600 (CU/INSTAAR)
;
; OPTIONAL INPUT PARAMETERS:
;   backstore:
;     If this keyword is set then backstoring
;     will be maintained by IDL instead of
;     the windowing environment.  This option may
;     be required for some IDL sessions running
;     in an emulated X-window environment.
;   colormap:
;     Set this keyword to specify the name of a text
;     file that defines a colormap.  This file should
;     be constructed with the CCG_RGBSAVE procedure.
;   nocolormap:
;     If set to one (1) then no colormap will be loaded.
;   iconify:
;     This keyword applies to the IDL X-window only.
;     If set then the IDL X-window is opened but
;     set as an icon.
;   landscape:
;     If set to one (1) then graphics device will be
;     set to landscape.  Default.
;   portrait:
;     If set to one (1) then graphics device will be
;     set to portrait.
;   saveas:
;     Save the graphics file in a user-provided file
;     name. saveas must also be passed to CCG_CLOSEDEV.
;   title:
;     Set this keyword to specify the name of the IDL
;     graphics window.  If not specified, the window
;     is given a label of the form "IDL n" where n is
;     the index number of the window.
;       win:
;     Set this keyword to specify graphics window.
;               If set to -1 then the IDL graphics window will
;               NOT be opened.  The default is set to win=0, e.g.,
;               IDL's default window.
;   xpixels:
;     Number of pixels in 'x' direction of IDL
;     X-window display.
;   ypixels:
;     Number of pixels in 'y' direction of IDL
;     X-window display.
;
; OUTPUTS:
;
;   pen:
;     Array corresponding to the RGB color indices
;     set by the default color map.
;
;   pcolor:
;     String vector containing a partial list of color names.
;
;     Note:  Users may use this procedure and choose to
;     overwrite the default colormap.  This is accomplished
;     by a first calling CCG_OPENDEV and then overwriting
;     the current colormap with another map.  However, the
;     'pen' vector may yield un-expected results.
;
;     The IDL routine 'CCG_EX_COLOR' provides a table of
;     colors from the default color map.
;
; COMMON BLOCKS:
;   None.
;
; SIDE EFFECTS:
;   None.
;
; RESTRICTIONS:
;   None.
;
; PROCEDURE:
;   Example implementation:
;
;     PRO example, dev=dev
;     .
;     .
;     .
;     CCG_OPENDEV,dev=dev,pen=pen,pcolor=pcolor
;     .
;     .
;     PLOT,x,y,PSYM=4,COLOR=pen(5)
;     XYOUTS,xnot,ynot,'test',COLOR=pen(2)
;     .
;     .
;     .
;     CCG_CLOSEDEV,dev=dev
;     END
;
;   From the IDL command line, the
;   procedure can be executed as
;   follows:
;
;   IDL>example      <- sends graphics to X-window
;   IDL>example,dev="phaser"  <- sends graphics to color PHASER 550
;
;
; MODIFICATION HISTORY:
;   Written,  KAM, April 1993.
;   Modified, KAM, November 1995.
;   Modified, KAM, March 1996.
;   Modified, KAM, October 1996.
;   Modified, KAM, September 1997.
;   Modified, KAM, June 1998.
;   Modified, KAM, December 1998.
;   Modified, KAM, March 1999.
;   Modified, KAM, December 2000.
;-
PRO     CCG_OPENDEV,   dev=dev,pen=pen,pcolor=pcolor,$
         saveas=saveas,win=win,$
         colormap=colormap,$
         nocolormap=nocolormap,$
         backstore=backstore,$
         landscape=landscape,$
         portrait=portrait,$
         font=font,$
         title=title,$
         iconify=iconify,$
         yoffset=yoffset,ysize=ysize,$
         xoffset=xoffset,xsize=xsize,$
         xpixels=xpixels,ypixels=ypixels
;
;----------------------------------------------- begin set up plot device
;
!P.MULTI=0
!P.FONT=(-1)
IF not keyword_set(font) then font='Helvetica'
IF NOT KEYWORD_SET(win) THEN win=0
IF NOT KEYWORD_SET(portrait) THEN BEGIN
    portrait=0
    landscape=1
ENDIF ELSE BEGIN
    portrait=1
    landscape=0
ENDELSE

if keyword_set(dev) then begin
    !p.charsize=1.2
    !p.charthick=1.5
    !p.thick=2.
    !x.thick=2.
    !y.thick=2.
endif

dir='z:\pc_idl\ccglib\'
IF NOT KEYWORD_SET(colormap) THEN colormap=dir+'data\color_comb1'

total_colors_available=256
;
;Define colors for various devices.
;
bwrgb=MAKE_ARRAY(total_colors_available,/INT,VALUE=1)
bwcol=MAKE_ARRAY(total_colors_available,/STR,VALUE="BLACK")

psrgb=[-1,1,2,3,4,5,6,7,8,9,10,11,12,13,14]
pscol=["N/A","BLACK","RED","CYAN","GREEN",$
      "BLUE","MAGENTA","PURPLE 1","GRAY",$
      "LIME","CINNAMON","ORANGE","PURPLE 2",$
      "YELLOW","WHITE"]
n=N_ELEMENTS(pscol)
psrgb=[psrgb,INDGEN(total_colors_available-n)+n]
pscol=[pscol,MAKE_ARRAY(total_colors_available-n,/STR,VALUE="UNDEFINED")]

xwrgb=[-1,14,2,3,4,5,6,7,8,9,10,11,12,13,1]
xwcol=["N/A","WHITE","RED","CYAN","GREEN",$
      "BLUE","MAGENTA","PURPLE 1","GRAY",$
      "LIME","CINNAMON","ORANGE","PURPLE 2",$
      "YELLOW","BLACK"]
n=N_ELEMENTS(xwcol)
xwrgb=[xwrgb,INDGEN(total_colors_available-n)+n]
xwcol=[xwcol,MAKE_ARRAY(total_colors_available-n,/STR,VALUE="UNDEFINED")]
;
IF KEYWORD_SET(dev) NE 0 THEN BEGIN
    ;
    ;units are cm
    ;
    IF NOT KEYWORD_SET(ysize) THEN ysize=17.75*landscape+22*portrait
    IF NOT KEYWORD_SET(xoffset) THEN xoffset=2*landscape+2*portrait

    IF NOT KEYWORD_SET(yoffset) THEN yoffset=26*landscape+3*portrait
    IF NOT KEYWORD_SET(xsize) THEN xsize=24.25*landscape+18*portrait
    ;
    ;What is 'saveas' file status?
    ;
    IF NOT KEYWORD_SET(saveas) THEN BEGIN
        z=(dev EQ 'psc') ? 'ps' : dev
        saveas=GETENV("HOME")+'/idl.'+z
    ENDIF
    ;
    ;Some printers require specific configuration
    ;of the DEVICE command others do not.
    ;Where possible, use common syntax.
    ;
    CASE dev of

    'ps':   driver='ps_bw'
    'lj5':     driver='ps_bw'
    'lj5_s':   driver='ps_bw'
    'optra':   driver='ps_bw'
    'optra_s': driver='ps_bw'
    'aerolj':  driver='ps_bw'
    'aerolj_s':    driver='ps_bw'
    'canon':   driver='ps_bw'
    'canon_s': driver='ps_bw'
    'culj4000':    driver='ps_bw'
    'o3lj':       driver='ps_bw'
    'o3lj_s':  driver='ps_bw'
    'lj8000_1':    driver='ps_bw'
    'lj8000_2':    driver='ps_bw'
    'lj8000_3d':   driver='ps_bw'
    'lj8000_3d_s': driver='ps_bw'
    'lj8000_3':    driver='ps_bw'
    'lj8000_4':    driver='ps_bw'
    'lj8000_2d':   driver='ps_bw'
    'lj8000_2d_s': driver='ps_bw'

    'psc':     driver='ps_color'
    'phaser':  driver='ps_color'
    'phasert': driver='ps_color'
    'phaser840':   driver='ps_color'
    'phaser840_s': driver='ps_color'
    'phaser840t':  driver='ps_color'
    'phaser850':   driver='ps_color'
    'phaser850_s': driver='ps_color'
    'phaser850t':  driver='ps_color'
    'eps':     driver='eps'
    'png':     driver='png'
    'culj5':   driver='ps_color'
    'hp4600':  driver='ps_color'

    ENDCASE

    CASE driver OF
    'ps_color':$
       BEGIN
       IF KEYWORD_SET(font) THEN BEGIN
         !P.FONT=0
         e={SET_FONT:font}
       ENDIF
       SET_PLOT, 'PS'
       DEVICE, FILENAME=saveas, /COLOR,$
         YOFFSET=yoffset, YSIZE=ysize, $
         XOFFSET=xoffset, XSIZE=xsize, $
         LANDSCAPE=landscape,$
         PORTRAIT=portrait,$
       ENCAPSULATED=0,$
         PREVIEW=0,$
         BITS=8,$
         _EXTRA=e
       pen=psrgb
       pcolor=pscol
       IF NOT KEYWORD_SET(nocolormap) THEN CCG_RGBLOAD,file=colormap
       END
    'ps_bw':$
       BEGIN
       IF KEYWORD_SET(font) THEN BEGIN
         !P.FONT=0
         e={SET_FONT:font}
       ENDIF
       SET_PLOT, 'PS'
       DEVICE, FILENAME=saveas,$
         YOFFSET=yoffset, YSIZE=ysize, $
         XOFFSET=xoffset, XSIZE=xsize, $
         LANDSCAPE=landscape,$
         ENCAPSULATED=0,$
         PREVIEW=0,$
         PORTRAIT=portrait,$
         _EXTRA=e
       pen=bwrgb
       pcolor=bwcol
       END
    'eps':$
       BEGIN
       IF KEYWORD_SET(font) THEN BEGIN
         !P.FONT=0
         e={SET_FONT:font}
       ENDIF
       SET_PLOT, 'PS'
       DEVICE, FILENAME=saveas, /COLOR,$
       YOFFSET=yoffset, YSIZE=ysize, $
       XOFFSET=xoffset, XSIZE=xsize, $
       LANDSCAPE=landscape,$
       PORTRAIT=portrait,$
         BITS_PER_PIXEL=8,$
         SET_FONT=font,$
         ENCAPSULATED=1,$
         PREVIEW=1,$
         _EXTRA=e
       pen=psrgb
       pcolor=pscol
       IF NOT KEYWORD_SET(nocolormap) THEN CCG_RGBLOAD,file=colormap
       END
    'png':$
       BEGIN
       ;
       ;units are pixels
       ;
       IF NOT KEYWORD_SET(ypixels) THEN ypixels=460*landscape+600*portrait
       IF NOT KEYWORD_SET(xpixels) THEN xpixels=600*landscape+460*portrait

       SET_PLOT, 'Z'
       DEVICE,   SET_RESOLUTION=[xpixels,ypixels],$
       Z_BUFFERING=0
       pen=psrgb
       pcolor=pscol
       IF NOT KEYWORD_SET(nocolormap) THEN CCG_RGBLOAD,file=colormap
       END
    ELSE:  CCG_FATALERR, dev+" device not recognized."

    ENDCASE
ENDIF ELSE BEGIN
    IF KEYWORD_SET(backstore) THEN retain=2 ELSE retain=1
    IF NOT KEYWORD_SET(iconify) THEN iconify=0 ELSE iconify=1
    ;
    ;units are pixels
    ;
    IF NOT KEYWORD_SET(ypixels) THEN ypixels=512*landscape+640*portrait
    IF NOT KEYWORD_SET(xpixels) THEN xpixels=640*landscape+512*portrait
    ;
    SET_PLOT,'WIN'
    DEVICE, decomposed=0
    IF win NE -1 THEN BEGIN
       IF KEYWORD_SET(title) THEN $
           WINDOW,win,title=title,xsize=xpixels,ysize=ypixels,$
         retain=retain $
       ELSE $
           WINDOW,win,xsize=xpixels,ysize=ypixels,retain=retain
       ERASE
       WSHOW,iconic=iconify
    ENDIF
    pen=xwrgb
    pcolor=xwcol
    IF NOT KEYWORD_SET(nocolormap) THEN CCG_RGBLOAD,file=colormap
ENDELSE
END