;+
; Overplots using oplot on to the GBT plotter's surface.  It also
; remembers the x and y values so that they can be replotted as needed
; (e.g. the x-axis changes).  Overplots, if toggled off, are
; automatically toggled on by a call to gbtoplot.
;
; @param x {in}{optional}{type=numerical vector} The x values to
; be plotted.  If omitted, then x is assumed to be channels starting
; at 0 and going through n_elements(y) - 1.  When supplied, it must
; have the same number of elements as y.  Unless chan is specified,
; this is assumed to be in the same units as the existing x axis.
;
; @param y {in}{required}{type=numerical vector}. The y values to
; be plotted.
;
; @keyword color {in}{optional}{type=long integer}{default=!g.oplotcolor}
; The color of the line to be plotted.
;
; @keyword chan {in}{optional}{type=boolean} When set, the x axis is
; assumed to be in channels and a conversion to the existing x axis is
; necessary to plot them.  That conversion is done using the header
; information of the primary plot (the argument to the most recent
; show).
;
; @keyword index {out}{optional}{type=integer} Returns the index
; associated with this oplot.  This index can be used to clear this
; over plot using clearoplots.  Note that once an index is cleared,
; subsequent indexes are renumbered - i.e. there are never any gaps in
; in index number.
;
; @version $Id: gbtoplot.pro,v 1.11 2005/04/29 06:02:19 bgarwood Exp $
;-
pro gbtoplot, x, y, color=color, chan=chan, index=index
    compile_opt idl2
    common gbtplot_common,mystate, xarray

    if n_params() eq 0 then begin
        message,'Usage: gbtoplot, [x,] y[, color=color, /chan, index=index]',/info
        return
    endif
    ok = gbtplot()
    if not ok then begin
        message,'No plotter!  Check your DISPLAY environment variable setting.',/info
        return
    endif

    ; just one argument?
    if (n_params() eq 1) then begin
        ; just y
        y = x
        x = findgen(n_elements(y))
        chan = 1
    endif else begin
        if (n_elements(y) ne n_elements(x)) then begin
            message,'x and y must have the same number of elements',/info
            return
        endif
    endelse

    if (not mystate.overplots) then mystate.overplots = 1

    if (keyword_set(chan)) then begin
        parsexunit, mystate.xunit, curscale, curtype
        x = convertxvalues(*mystate.dc_ptr, x, 1.0d, 0, '', '', 0.d, 0.d, $
                 curscale, curtype, mystate.frame, mystate.veldef, mystate.xoffset, mystate.voffset)
    endif

    if (not keyword_set(color)) then color = !g.oplotcolor

    ostruct = {x:double(x), y:y, color:color, next:ptr_new()}

    ; append to the end of the list
    thisptr = mystate.oplots_ptr
    index = 0
    if (ptr_valid(thisptr)) then begin
        while (1) do begin
            index += 1
            if (not ptr_valid((*thisptr).next)) then begin
                (*thisptr).next = ptr_new(ostruct)
                break
            endif
            thisptr = (*thisptr).next
        endwhile
    endif else begin
        mystate.oplots_ptr = ptr_new(ostruct)
    endelse

    ; and plot just this one

    wset,mystate.win_id
    if (color ge 0) then begin
        oplot,ostruct.x,y,color=color
        wset,mystate.pix_id
        oplot,ostruct.x,y,color=color
    endif else begin
        oplot,ostruct.x,y
        wset,mystate.pix_id
        oplot,ostruct.x,y
    endelse
    ; without this next wset, strangly nothing is seen.  Hmmm.
    wset,mystate.win_id
    wset,-1
end