NAME

     ilHwPass -	a pass through the graphics pipe

INHERITS FROM

     ilLink

HEADER FILE

     #include <il/ilHwPass.h>

CLASS DESCRIPTION

     ilHwPass encodes the hardware acceleration	for an ilImage (or an
     ilImgStat). A table of ilHwPass instances,	one per	ilHwConnection/visual
     type combination (encoded via ilHwTarget),	is hung	off of each ilImage
     via ilImage::hwPassTable (or ilImgStat::hwPassTable). The ilHwPass
     associated	with a particular ilHwTarget is	retrieved via
     ilImage::hwGetPass() (or ilImgStat::hwGetPass()). Calls to	hwGetPass()
     cause ilHwPass's to be created and	cached if they don't exist yet.

     An	ilHwPass stores	pointers to the	ilHwTarget it is for (target), its
     source of image data (inImg), which ilImage (or ilImgStat)	it's a pass
     for (via its ilLink parent), and the last ilImage in the pass chain
     (parentImg).

CLASS MEMBER FUNCTION SUMMARY

     Constructor

	  ilHwPass(ilLink* parent, const ilHwTarget& target)

     Setup methods

	  void setup(const ilHwOp& op)
	  int needsSetup()

     I/O methods

	  virtual ilStatus drawTile(ilMpNode* parent, float x, float y,
				    float z, int nx, int ny,
				    ilHwImg* hwImg, int	fx, int	fy,
				    int	buffEnables=0, ilHwHintList* hints=NULL,
				    ilMpManager** pMgr=NULL)
	  virtual ilStatus readTile(ilMpNode* parent, int x, int y,
				    int	z, int nx, int ny, int nz,
				    void*& data, int dx, int dy,
				    int	dz, int	dnx, int dny,
				    int	dnz, const ilConfig* cfg,
				    ilMpManager** pMgr=NULL)
	  virtual ilStatus getStat(unsigned long* hist,	double&	min,
				   double& max,	int chan)




     Miscellaneous queries

	  ilHwConnection* getConnection()
	  int getClass()
	  int getID()
	  int isRgb()
	  ilImage* getParentImg()
	  ilImage* getInput()
	  ilFrameBufferImg* getLastFbImg();
	  GLubyte* getRgbFill()
	  int getCiFill()
	  static ilNopImg* getNopImg(ilImage* img);

     Methods for derived classes

	  virtual void checkOp(const ilHwOp& op)  protected
	  void copy(ilHwPass* pass)	protected
	  void updateLastFbImg(ilFrameBufferImg* fbImg)	 protected
	  void calcFill()     protected
	  void calcCapabilities()  protected
	  int canAlterInput(ilImage* input=NULL)  protected
	  int doesRGB()	 protected
	  int doesLuminance() protected
	  int doesScale()     protected
	  int doesZoom() protected
	  int doesFracZoom()  protected
	  int doesTexture()   protected

FUNCTION DESCRIPTIONS

     ilHwPass()

	  ilHwPass(ilLink* parent, const ilHwTarget& target)


	  Constructs a hardware	pass with the indicated	parent that it is the
	  end of the chain it is accelerating.	The target specifies the
	  server connection and	visual class for the rendering.	 See
	  ilHwTarget(3)	for more details on the	target specification.

     calcCapabilities()

	  void calcCapabilities()  protected


	  This method is called	to determine what the hardware supports	on
	  this visual.	It must	be called before using any of the does*()
	  methods.




     calcFill()

	  void calcFill()     protected


	  This method computes the appropriate fill value (based on the	parent
	  image	and our	visual).

     canAlterInput()

	  int canAlterInput(ilImage* input = NULL)  protected


	  This methos returns TRUE if the input	is a related image, but	is not
	  a color image	that was allocated by ilOpImg. The pass	cannot alter
	  any image that can affect the	application chain (including the pass'
	  parent).

     checkOp()

	  virtual void checkOp(const ilHwOp& op)  protected


	  This pure virtual method checks for the validity of an operation.
	  It is	called from setup after	the parent and input images are	filled
	  in.  It is the responsibility	of derived classes to supply the
	  implementation of this method.

     copy()

	  void copy(ilHwPass* pass)	protected


	  This method copies another hardware pass's parameters	onto ourself.
	  Derived classes need to do something about their own parameters and
	  call this method.

     doesFracZoom()

	  int doesFracZoom()  protected


	  This method returns true if fractional zoom is supported by hardware
	  for the visual that we are using. This method	must not be called
	  before calling calcCapabilites().







     doesLuminance()

	  int doesLuminance() protected


	  This method returns true if conversion of luminance data is
	  supported by hardware	for the	visual that we are using. This method
	  must not be called before calling calcCapabilites().

     doesRGB()

	  int doesRGB()	 protected


	  This method returns true if conversion of RGB	data is	supported by
	  hardware for the visual that we are using. This method must not be
	  called before	calling	calcCapabilites().

     doesScale()

	  int doesScale()     protected


	  This method returns true if scaling of data is supported by hardware
	  for the visual that we are using. This method	must not be called
	  before calling calcCapabilites().

     doesTexture()

	  int doesTexture()   protected


	  This method returns true if texture rendering	is supported by
	  hardware for the visual that we are using. This method must not be
	  called before	calling	calcCapabilites().

     doesZoom()

	  int doesZoom() protected


	  This method returns true if pixel zooming is supported by hardware
	  for the visual that we are using. This method	must not be called
	  before calling calcCapabilites().








     drawTile()

	  virtual ilStatus drawTile(ilMpNode* parent, float x, float y,
				    float z, int nx, int ny,
				    ilHwImg* hwImg, int	fx, int	fy,
				    int	buffEnables=0, ilHwHintList* hints=NULL,
				    ilMpManager** pMgr=NULL)


	  This method draw the pass's parent image tile	(x,y,z,	nx,ny,1) in
	  the given hardware image, hwImg, at location (fx,fy).	 All
	  coordinates are in the hardware image's orientation (e.g.,
	  lowerleft, etc.)

	  The parent MP	node will have this operation added as a dependent
	  node and the MP manager for this queued operation can	be returned
	  via the mpMgr	parameter.  Both of these paramters may	be NULL.

	  The buffEnables is a mask containing the buffers (e.g.,
	  ilFrontBuffer) that should be	enabled	for the	drawing	operation. The
	  hints	is a list of view specific hints that may be used by the draw
	  operation.

     getCiFill()

	  int getCiFill()


	  This method returns a	color index fill value calculated from
	  parentImg's fill value.

     getClass()

	  int getClass()


	  This method returns the Visual class associated with this pass.

     getConnection()

	  ilHwConnection* getConnection()


	  This method returns the ilHwConnection associated with this pass.








     getID()

	  int getID()


	  This method returns an encoding of the ilHwConnection	associated
	  with this pass and the Visual	class.	This is	intended solely	for
	  use with ilHwPassTable.

     getInput()

	  ilImage* getInput()


	  This method returns the pass's input image.

     getLastFbImg()

	  ilFrameBufferImg* getLastFbImg()


	  This method returns the last framebuffer image used with this	pass.

     getNopImg()

	  ilNopImg* getNopImg(ilImage* img)


	  This method chains on	a "related" ilNopImg on	to the image specified
	  by img.  Related images are automatically deleted when their input
	  is deleted.

     getParentImg()

	  ilImage* getParentImg()


	  This method returns the pass's parent	image.	The ilLink parent and
	  parentImg are	the same for ilImage's.	For ilImgStat's, the ilLink
	  parent points	at the ilImgStat and parentImg points at the
	  ilImgStat's source ilImage.

     getRgbFill()

	  GLubyte* getRgbFill()


	  This method returns an RGB fill value	calculated from	parentImg's
	  fill value.



     getStat()

	  virtual ilStatus getStat(unsigned long* hist,	double&	min,
				   double& max,	int chan)


	  This method gets statistics for the channel specified	by chan	and
	  returns them in hist,	min and	max.  This assumes that	a drawTile()
	  has been performed with ilHwOpStat selected. It is the callers
	  responsibility to ensure that	the data area associated with hist is
	  appropriately	sized for the returned statistics.

     isRgb()

	  int isRgb()


	  This method returns true if the Visual associated with this pass is
	  TrueColor or DirectColor.

     needsSetup()

	  int needsSetup()


	  Thie method returns true if the pass needs to	have setup() called
	  because something about it's input has been changed.

     readTile()

	  virtual ilStatus readTile(ilMpNode* parent, int x, int y,
				    int	z, int nx, int ny, int nz,
				    void*& data, int dx, int dy,
				    int	dz, int	dnx, int dny,
				    int	dnz, const ilConfig* cfg,
				    ilMpManager** pMgr=NULL)


	  This virtual method reads back the processed data corresponding to
	  the pass's parent image tile (x,y,z, nx,ny,nz) and places it in the
	  buffer, data,	with coordinates (dx,dy,dz, dnx,dny,dnz). The
	  attributes of	the buffer are determined by the parent	image unless
	  overridden by	cfg.

	  The parent MP	node will have this operation added as a dependent
	  node and the MP manager for this queued operation can	be returned
	  via the mpMgr	parameter. Both	of these paramters may be NULL.





     setup()

	  void setup(const ilHwOp& op)


	  This method sets up this ilHwPass for	the operation defined by op.
	  This method fills in the parent and input image fields and then
	  calls	the checkOp() virtual method to	determine if the operation can
	  be implemented.

     updateLastFbImg()

	  void updateLastFbImg(ilFrameBufferImg* fbImg)	 protected


	  This method updates the last last framebuffer	image used with	this
	  pass.

INHERITED MEMBER FUNCTIONS

   Inherited from ilLink
     addResetCallback(), alterAction(),	anyAltered(), clearAllowed(),
     clearSet(), clearStatus(),	deleteRelated(), disableAltered(),
     dumpChain(), getClassPropSet(), getDescription(), getDirectParent(),
     getDisabledIndex(), getFloatProp(), getGenerationID(), getIntProp(),
     getMaxIndex(), getMinIndex(), getNumChildren(), getNumParents(),
     getParent(), getProp(), getProp(),	getPropSet(), getPtrProp(),
     getRelatedChild(),	getRelatedDelete(), getRelatedType(), getStatus(),
     hasResetCallbacks(), ilGetClassPropSet(), inProgress(), isAllowed(),
     isAltered(), isEnabled(), isRelated(), isSet(), markSet(),	mpUnlock(),
     neverReset(), newRelatedType(), removeParent(), removeProp(),
     removeResetCallback(), reset(), resetAltered(), resetCheck(),
     setAllowed(), setAltered(), setDescription(), setDisabledIndex(),
     setEnabled(), setParent(),	setProp(), setPropAltered(),
     setRelatedDelete(), setRelatedType(), setStatus(),	stopWatching(),
     unalterable(), watch(), watchNotify()

SEE ALSO

     ilHwConnection(3),	ilHwContext(3),	ilHwVisual(3), ilHwPassGL(3)