[Insight-developers] Is this right? -- beefed up GetOutput() doc

[Mark Foskey]

I needed to access some image information partway through a pipeline, 
and it took me a while to settle on the proper way to do that.  I 
thought it would help clarify things if the GetOutput() documentation 
were more detailed.  I wrote up the following, but since the dashboard 
won't catch any factual errors, I thought I'd post this before checking 
it in.  (The fact that I feel the need to seek confirmation argues that 
the documentation would be useful.)

The User's Guide was helpful in this, but I thought this information 
ought to be available from the doxygen docs as well.

   /** Get the output data of this process object.  The output of this
    * function is not valid until an appropriate Update() method has
    * been called, either explicitly or implicitly.  Both the filter
    * itself and the image object have Update() methods, and both
    * methods update the image data.  Here are three ways to use
    * GetOutput() and make sure the image data is valid.  In these
    * examples, \a image is a pointer to some Image object, and the
    * particular ProcessObjects involved are filters.
    *
    * \code
    *   anotherFilter->SetInput( someFilter->GetOutput() );
    *   anotherFilter->Update();
    * \endcode
    * (This pipelining method is preferred where feasible since it
    * permits more efficient use of memory and other resources.)
    *
    * \code
    *   image = someFilter->GetOutput();
    *   image->Update();
    * \endcode
    *
    * \code
    *   someFilter->Update();
    *   image = someFilter->GetOutput();
    * \endcode
    * (In the above example, the two lines of code can be in
    * either order.)
    *
    * Note that Update() is not called automatically except within a
    * pipeline as in the first example.
    */


-- 
Mark Foskey    (919) 843-5436  Computer-Aided Diagnosis and Display Lab
mark_foskey@unc.edu            Department of Radiology, CB 7515, UNC
http://www.cs.unc.edu/~foskey  Chapel Hill, NC  27599-7515