[vtk-developers] RE: API Change

[Will Schroeder]

Hey Bill-

Quite frankly I have been annoyed with this particular API change as 
well. But when it gets down to it, the problem is with Microsoft's 
sucky compiler. As far as I understand, we are faced with problems no 
matter what we do, either inconsistencies in API or compile/link 
problems. Or if we again include windows.h everywhere there is the 
big hit on compile time, not to mention that (I suspect) in some 
cases the compiler will die because of too many includes.

(Bill, please indulge me here while I belabor this because I am 
forwarding this email to others who have not seen some of these discussions.)

What I do with my applications is to require them to built against a 
particular version of VTK. I don't like to try to keep an application 
running on different versions of a library, whether it's VTK or 
other. Instead I depend on the tag/branch facilities of CVS. and make 
sure everything stays in synch. I prefer to move forward 'cause I 
don't like carrying the complexity around. Such API changes are very 
painful to me, Kitware, and the community (I have to go through 
several books, not to mention the various applications that we build 
on top of VTK). But I have seen what happens to a complicated 
software system when the API does not change and past features 
linger...a slow suffocation under its own weight/complexity. Of 
course, we could just come out with a new system each time 
(psychologically, adapting to a new system seems easier somehow), but 
this is no different than picking a version and sticking with it, 
except that the expectation is that with a new version there is 
backward compatibility, which is where the psychology gets bad when 
this doesn't happen.

We do try, sometimes we fail, to mark methods deprecated and keep 
them around for a while before removing them. And I'm not sure what 
to do about evolving software like the widgets, which are going 
through a big redesign. We are actually doing some cutting edge work 
here and none of us knows at this point how it's going to work out 
until we can use it for a while. Which means that API will certainly 
be broken along the way.

BTW Bill-- Ross Whitaker, you and I are supposed to come up with a 
backwards compatibility policy for the ITK Developer's Meeting in 
October (Stephen expects us to give a report). I can take an initial 
crack and we can iterate together.

Will



At 02:45 PM 9/4/2005, Lorensen, William E \(Research\) wrote:
>I guess we have different philosophies. I would prefer to protect 
>the large installed base of VTK users and keep the ugliness within VTK itself.
>
>Bill
>
>-----Original Message-----
>From: Brad King [mailto:brad.king at kitware.com]
>Sent: Sunday, September 04, 2005 12:21 PM
>To: Bill Lorensen
>Cc: Sebastien BARRE; will Schroeder; Lorensen, William E (Research)
>Subject: Re: API Change
>
>
>Bill Lorensen wrote:
> > I can't follow the reasoning in that thread. Why couldn't AddProp be
> > retained, just calling AddViewProp? Seems like an arbitrary API change.
>
>A full explanation of the windows.h change is here:
>
>http://www.vtk.org/cgi-bin/viewcvs.cgi/Utilities/Upgrading/README.WindowsMangling.txt?rev=HEAD&view=auto
>
>If AddProp is retained then RemoveProp should be retained too.  In order
>to retain RemoveProp and work with sources that include windows.h the
>definition must look like this:
>
>#ifdef VTK_WORKAROUND_WINDOWS_MANGLE
># define RemovePropA RemoveProp
># define RemovePropW RemoveProp
>#endif
>    void RemoveProp(vtkProp*);
>#ifdef VTK_WORKAROUND_WINDOWS_MANGLE
># undef RemovePropA
># undef RemovePropW
>    //BTX
>    void RemovePropA(vtkProp*);
>    void RemovePropW(vtkProp*);
>    //ETX
>#endif
>
>This ugliness is the reason the "Prop" API was deprecated and replaced
>with the "ViewProp" API.
>
>  >
>  > I noticed that Viewport's API changed recently. For example AddProp
>no longer exists. Why was it removed?
>  >  We have code now that needs lines like this:
>  >
>  > #if (VTK_MAJOR_VERSION == 4 && VTK_MINOR_VERSION <= 5)
>  >  foo->AddProp( volume );
>  > #else
>  >  foo->AddViewProp( volume );
>  > #endif
>
>Unfortunately this is inevitable when an API is deprecated and you want
>to write code that works with both the old and new version.  You can
>reduce the number of places that look like that by writing a header with
>code like this:
>
>template <class L, class R>
>void myprojAddProp(L l, R r)
>{
>#if VTK_MAJOR_VERSION > 4 || \
>     (VTK_MAJOR_VERSION == 4 && VTK_MINOR_VERSION >= 5)
>   l->AddViewProp(r);
>#else
>   l->AddProp(r);
>#endif
>}
>
>and then everywhere else just replace
>
>foo->AddProp(volume)
>
>with
>
>myprojAddProp(foo, volume)
>
>It is up to you whether this is more readable or easier to maintain than
>your current solution.
>
>-Brad