;+
; NAME:
;	RGBO_DepthCue
; PURPOSE:
;	Returns a matte matrix for a depth cue operation
; CATEGORY:
;	gen/idl/toolbox/graphics
; CALLING SEQUENCE:
	PRO RGBO_DepthCue, cue_depth=cue_depth, size=sz, dimension=dimension, matte=matte
; INPUTS:
;	cue_depth=cue_depth	scalar or array[2]; type: float
;							scalar is interpreted as [depth,depth]
;							depth[0]: opacity at maximum depth
;							depth[1]: power applied to dropoff from minimum to
;							maximum depth (should be positive)
; OPTIONAL INPUT PARAMETERS:
;	size=sz				array; type: integer
;							IDL size vector for 3D array
;							only the dimensions sz[1:sz[0]] are used
;	dimension=dimension	array[3]; type: integer
;							dimensions of 3D array
;
;							Either one of these keyword is used to specify the dimensions
;							of a 3D array [N,L,M]
;
;	matte=matte			array[N,L,M]; type: float
;							The matte matrix for the depth cue is multiplied into
;							the input matte, if it exists
; OUTPUTS:
;	matte=matte			array[N,L,M]; type: float
;							resulting matte matrix (input matte times depth cue matte)
; INCLUDE:
	@compile_opt.pro			; On error, return to caller
; CALLS:
;	SuperArray, IsType
; SEE ALSO:
;	RGBO_Project
; PROCEDURE:
;	The 3rd dimension of M is taken to be the z-dimension.
;	m=0 has maximum depth (farthest away from the viewer) and gets opacity
;	depth[0]. m=M-1 has minimum depth (nearest to the viewer) and gets opacity
;	of one. The dropoff between the two is given by the power value:
;		o = depth[0]+(1-depth[0])*( z/(ndim[2]-1)  )^depth[1]
;	The resulting values are constrained to stay between 0 and 1.
; MODIFICATION HISTORY:
;	AUG-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;-

IF n_elements(sz       ) NE 0 THEN ndim = sz[1:sz[0]]
IF n_elements(dimension) NE 0 THEN ndim = dimension

CASE n_elements(cue_depth) OF
0   : RETURN					; Return without changing or creating matte
1   : powr = 1.0
2   : powr = cue_depth[1]		; power for opacity dropoff
ELSE: powr = 1.0
ENDCASE

rmax = ndim[2]-1.0				; z index close to viewer
rmin = 0.0						; z index far from viewer
omax = 1.0						; opacity near viewer
omin = cue_depth[0]				; opacity far from viewer


r = indgen(ndim[2])
r = SuperArray(r, ndim[0]*ndim[1], /lead)
r = reform(r, ndim, /overwrite)

r = omin+(omax-omin)*( (r-rmin)/(rmax-rmin)  )^powr
r = (r > 0.0) < 1.0

CASE IsType(matte, /undefined) OF
0: matte = r*matte
1: matte = r
ENDCASE

message, /info, 'depth cueing on'

RETURN  &  END