VTK/Wrapping hints: Difference between revisions

From KitwarePublic
< VTK
Jump to navigationJump to search
(Created page with "Sometimes the VTK wrappers need a little help in order to properly wrap certain C++ methods. Most often, this occurs when a method takes or returns a pointer. Some examples o...")
 
No edit summary
Line 23: Line 23:
</pre>
</pre>


Once this macro is defined, we can use it in our method declarations:
Once this macro is defined, we can use it in our method declarations.
 
<pre>
VTK_NEWINSTANCE
vtkObjectBase* NewInstance();
</pre>


The hint attributes that VTK provides are as follows:
The hint attributes that VTK provides are as follows:
Line 36: Line 31:
This indicates that the method returns a vtkObject that has just been created, and the caller must call Delete() on the returned value when done with it.
This indicates that the method returns a vtkObject that has just been created, and the caller must call Delete() on the returned value when done with it.


===[[<nowiki />vtk::sizehint(n)]] (not done yet)===
<pre>
VTK_NEWINSTANCE
vtkObjectBase* NewInstance();
</pre>
 
===[[<nowiki />vtk::sizehint(n)]]===


This indicates that a returned pointer, such as 'float *', points to an array of 'n' values.
This indicates that a returned pointer, such as 'float *', points to an array of 'n' values.
<pre>
VTK_SIZEHINT(3)
double* GetPoint();
</pre>

Revision as of 12:52, 6 June 2016

Sometimes the VTK wrappers need a little help in order to properly wrap certain C++ methods. Most often, this occurs when a method takes or returns a pointer. Some examples of the "unknowns" for a pointer that might have to be hinted are:

  • Does the API allow the pointer to be NULL?
  • Does it point to a single object, or an array?
  • If an array, what is the size of the array?
  • Will 'delete' or 'free()' have to be called to free the memory?
  • If the pointer is 'char *', is it null-terminated? Is it ASCII, utf-8, or latin1?

Hinting with attributes

C++11 introduced attributes to provide hints for the compiler, such as the [[noreturn]] attribute to indicate that a method will never return:

[[noreturn]] void exit(int status);

We are allowed to define our own attributes, as long as we define a unique namespace, e.g. [[vtk::name]]. However, we don't want the attributes to be be "naked" in the code, because that would break pre-C++11 compilers. Instead, we conditionally define the attributes within macros (this is done within vtkSetGet.h, as for most VTK macros).

 #ifdef __VTK_WRAP__
 #define VTK_NEWINSTANCE [[vtk::newinstance]]
 #else
 #define VTK_NEWINSTANCE
 #endif

Once this macro is defined, we can use it in our method declarations.

The hint attributes that VTK provides are as follows:

[[vtk::newinstance]]

This indicates that the method returns a vtkObject that has just been created, and the caller must call Delete() on the returned value when done with it.

VTK_NEWINSTANCE
vtkObjectBase* NewInstance();

[[vtk::sizehint(n)]]

This indicates that a returned pointer, such as 'float *', points to an array of 'n' values.

VTK_SIZEHINT(3)
double* GetPoint();