https://public.kitware.com/Wiki/api.php?action=feedcontributions&user=Martink&feedformat=atomKitwarePublic - User contributions [en]2024-03-29T11:58:11ZUser contributionsMediaWiki 1.38.6https://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=62227Shaders In VTK2018-04-02T12:33:54Z<p>Martink: </p>
<hr />
<div><br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK is based on OpenGL version 3.2 or later.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders should name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assume their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Textures=<br />
<br />
Any vtkTextures assigned to the actor/property will get declared and bound for use in the shader. The names as of VTK 9.0 will be colortexture for the texture used in texture based scalar coloring, actortexture for the actor's texture, and property textures will be named based on the name you passed to SetTexture. The order is that the Actor's texture gets processed first followed by any textures specified in the property. The actual texture unit used for a texture is unknown, but you can count on it having a texture unit and being active when the shader is executed.<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=62213Shaders In VTK2018-03-05T16:22:59Z<p>Martink: </p>
<hr />
<div><br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders should name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assume their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Textures=<br />
<br />
Any vtkTextures assigned to the actor/property will get declared and bound for use in the shader. The names as of VTK 9.0 will be colortexture for the texture used in texture based scalar coloring, actortexture for the actor's texture, and property textures will be named based on the name you passed to SetTexture. The order is that the Actor's texture gets processed first followed by any textures specified in the property. The actual texture unit used for a texture is unknown, but you can count on it having a texture unit and being active when the shader is executed.<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shader_In_VTK&diff=61820Shader In VTK2017-05-23T13:23:29Z<p>Martink: Martink moved page Shader In VTK to Shaders In VTK</p>
<hr />
<div>#REDIRECT [[Shaders In VTK]]</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=61819Shaders In VTK2017-05-23T13:23:29Z<p>Martink: Martink moved page Shader In VTK to Shaders In VTK</p>
<hr />
<div><br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders should name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assume their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Textures=<br />
<br />
Any vtkTextures assigned to the actor/property will get declared and bound for use in the shader. The names will be texture_0 through texture_N. The order is that the Actor's texture gets processed first followed by any textures specified in the property. The actual texture unit used for a texture is unknown, but you can count on it having a texture unit and being active when the shader is executed.<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=61818Shaders In VTK2017-05-23T13:22:41Z<p>Martink: </p>
<hr />
<div><br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders should name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assume their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Textures=<br />
<br />
Any vtkTextures assigned to the actor/property will get declared and bound for use in the shader. The names will be texture_0 through texture_N. The order is that the Actor's texture gets processed first followed by any textures specified in the property. The actual texture unit used for a texture is unknown, but you can count on it having a texture unit and being active when the shader is executed.<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=61817Shaders In VTK2017-05-23T13:20:55Z<p>Martink: provide some information on textures/samplers</p>
<hr />
<div><font color=red>in progress...</font><br />
<br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders should name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assume their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Textures=<br />
<br />
Any vtkTextures assigned to the actor/property will get declared and bound for use in the shader. The names will be texture_0 through texture_N. The order is that the Actor's texture gets processed first followed by any textures specified in the property. The actual texture unit used for a texture is unknown, but you can count on it having a texture unit and being active when the shader is executed.<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=59128Shaders In VTK2016-02-17T20:16:35Z<p>Martink: /* Basics */</p>
<hr />
<div><font color=red>in progress...</font><br />
<br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders should name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assume their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=59127Shaders In VTK2016-02-17T20:15:27Z<p>Martink: /* PolyDataMapper */</p>
<hr />
<div><font color=red>in progress...</font><br />
<br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders shoudl name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assuming their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=59126Shaders In VTK2016-02-17T20:14:45Z<p>Martink: /* PolyDataMapper */</p>
<hr />
<div><font color=red>in progress...</font><br />
<br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders shoudl name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assuming their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=PolyDataMapper=<br />
<br />
The vtkOpenGLPolyDataMapper is probably the most complex shader in VTK and is designed to handle many different situations. As such we have provided a few methods to support customizing the shader to various degrees. The first methods are<br />
<br />
void AddShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst, // do this replacement before the default<br />
std::string replacementValue,<br />
bool replaceAll);<br />
void ClearShaderReplacement(<br />
vtkShader::Type shaderType, // vertex, fragment, etc<br />
std::string originalValue,<br />
bool replaceFirst);<br />
<br />
which allow you to specify your own string replacements to use in the shader. For example see [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader.cxx] <br />
<br />
the other methods allow you to completely override the shader code that is used.<br />
<br />
vtkSetStringMacro(VertexShaderCode);<br />
vtkGetStringMacro(VertexShaderCode);<br />
vtkSetStringMacro(FragmentShaderCode);<br />
vtkGetStringMacro(FragmentShaderCode);<br />
vtkSetStringMacro(GeometryShaderCode);<br />
vtkGetStringMacro(GeometryShaderCode);<br />
<br />
you can find an example of using these along with specifying your own uniforms here [https://gitlab.kitware.com/vtk/vtk/blob/v7.0.0.rc2/Rendering/OpenGL2/Testing/Cxx/TestUserShader2.cxx]<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=59125Shaders In VTK2016-02-17T20:06:43Z<p>Martink: /* Basics */</p>
<hr />
<div><font color=red>in progress...</font><br />
<br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK consist of three strings consisting of the vertex, fragment and geometry shader code. The geometry shader code is optional, the other two are required. The vtkOpenGLShaderCache handles caching shaders to improve performance. Shaders are stored in vtkShaders and combined into a vtkShaderProgram. You will likely never need to work with those two classes as the vtkOpenGLShaderCache is the main entrance point for creating and binding shaders.<br />
<br />
Structure of a Shader<br />
<br />
VTK uses shaders to perform its OpenGL rendering. VTK supports many different<br />
options when it comes to rendering, resulting in potentially thousands of<br />
possible combinations. While we could make one giant shader that uses defines or<br />
uniforms to switch between all these possibilities it would be limiting. Instead<br />
we build up the shader using string replacements on the fly, and then cache the<br />
results for performance.<br />
<br />
When writing your own shaders you can use any approach you want. In the end they<br />
are just strings of code. For vtkOpenGLPolyDataMapper we make use of heavy<br />
string replacments. In other classes we do very little processing as the shader<br />
has far fewer options. Regardless there are a few conventions you should be<br />
aware of.<br />
<br />
For shader replacements we tend to use a form of<br />
<br />
//VTK::SomeConcept::SomeAction<br />
<br />
For example<br />
<br />
//VTK::Normal::Dec - declaration any uniforms/varying needed for normals<br />
//VTK::Normal::Impl - Implementation of shader code for handling normals<br />
<br />
All shaders should start with the following line<br />
<br />
//VTK::System::Dec<br />
<br />
Which vtkOpenGLShaderCache will replace with a #version and some other values to<br />
match the system and OpenGL Context it has. The other line you need (only in<br />
your fragment shader) is<br />
<br />
//VTK::Output::Dec<br />
<br />
which VTK uses to map shader outputs to the framebufer.<br />
<br />
All vertex shaders should name their outputs with a postfix of VSOutput All<br />
geometry shaders should name their outputs with a postfix of GSOutput All<br />
fragment shaders shoudl name their inputs with a postfix of VSOutput. Put<br />
another way fragment shaders should assuming their input is coming from the<br />
vertex shader. If a geometry shader is present VTK will rename the fragment<br />
shader inputs from VSOutput to GSOuput automatically.<br />
<br />
Variables that represent positions or directions usually have a suffix<br />
indicating the coordinate system they are in. The possible values are<br />
<br />
*MC - Model Coordinates<br />
*WC - WC world coordinates<br />
*VC - View Coordinates<br />
*DC - Display Coordinates<br />
*NVC - NormalizeViewCoordinates<br />
<br />
=Issues=<br />
* When a material is unloaded, if any PropertyUniforms are present in the material description, they remain after the shader has been unset i.e. there is not way to unload a material and return to the state of the property/actor before the material was loaded. The correct behaviour is that the property values return to the ones which the user set last (or those which we present before the material was loaded) when a material in unloaded.<br />
<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=Shaders_In_VTK&diff=59124Shaders In VTK2016-02-17T19:57:44Z<p>Martink: /* Introduction */</p>
<hr />
<div><font color=red>in progress...</font><br />
<br />
=Introduction=<br />
<br />
This document describes the Shader support in VTK. In 2015 we created a new OpenGL backend fully based on shaders. This is the default backend for VTK versions 7.0 and later. You can extend some mapper's shaders using methods the mapper's provide. You can also subclass to create your own mappers that have custom shaders. VTK guarantees you will have at least OpenGL version 2.1 with the gpu_shader4 extension or version 3.2.<br />
<br />
=Basics=<br />
<br />
The shaders in VTK are encapsulated in a '''Material'''. A material is described in a xml file. The format of this file is discussed later<font color=red>*TODO*</font color=red>). The material description may include<br />
* vertex/fragment shaders<br />
* uniform variables passed to the shaders<br />
* surface properties i.e. attribute values for vtkProperty such as AmbientColor,Specular etc.<br />
<br />
To apply a material to an actor, the material must be ''loaded'' on the actor's property using vtkProperty::LoadMaterial(const char*). The argument can be a location a xml file describing the material, or name of a material defined by VTK MaterialLibrary (vtkMaterialLibrary). (It can also be a material provided in the Material Repository, but we will discuss that later <font color=red>*TODO*</font color=red>).<br />
<br />
When a material is loaded successfully, the vtkProperty is updated using the surface property values defined in the xml. It also instantiates an appropriate vtkShaderProgram subclass, which manages all the shaders defined in the XML. Currently, shaders with different languages cannot be used in the same material. The ShaderProgram compiles the shader code and binds the shaders everytime the actor is rendered.<br />
<br />
The uniform parameters passed to the Shaders can be of following types:<br />
* Parameters whose values are constants defined in the xml: these are identified with xml tag '''Uniform'''<br />
* Parameters whose values are constants defined at runtime. These are called application uniform variables. These are identified by tag '''ApplicationUniform'''. The value for Application uniform variables can be set at run time using vtkProperty::AddShaderVariable. (NOTE: we are planning to merge the distinction between Uniform with ''value'' specified in xml or at runtime. Once that's done, it will be possible to change the value of any Uniform variable at run time using vtkProperty::AddShaderVariable).<br />
* Parameters whose values are obtained from the active vtkCamera during rendering: these are identified by xml tag '''CameraUniform'''.<br />
* Parameters whose values are obtained from the vtkProperty to which this material is applied: these are '''PropertyUniform''' parameters.<br />
* Parameters whose values are obtained from the Lights in the renderer: '''LightUniform'''.<br />
* Parameters which are data matrices (or in case of Cg, can be GL state matrices): '''MatrixUniform'''.<br />
* Parameters which are textures/samplers: '''SamplerUniform'''.<br />
<br />
=Issues=<br />
* When a material is unloaded, if any PropertyUniforms are present in the material description, they remain after the shader has been unset i.e. there is not way to unload a material and return to the state of the property/actor before the material was loaded. The correct behaviour is that the property values return to the ones which the user set last (or those which we present before the material was loaded) when a material in unloaded.<br />
<br />
<br />
=Acknowledgements=<br />
* Shader support in VTK is a collaborative effort between Sandia National Labs and Kitware Inc.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=56032VTK/FAQ2014-04-04T18:12:05Z<p>Martink: /* Are answers for the exercises in the VTK book available? */</p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk can be found and downloaded from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Is there a mailing list for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos).<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://open.cdash.org/index.php?project=VTK<br />
<br />
VTK uses CTest/CDash to perform builds, run tests, and generate dashboards. You<br />
can find more information about CDash at: http://cdash.org<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
because the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and Google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# The VTK 4.x CVS nightly/development distribution supports Tcl/Tk 8.4 as long as you use a release version of CMake > 1.4.5. Since VTK 4.2 will require CMake 1.6, the next release version will support Tcl/Tk 8.4.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# Bad triangles are present: e.g., triangles with duplicate vertices such as (1,2,1) or (100,100,112), or (57,57,57), and so on. Solution: use ''vtkCleanPolyData''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. <br />
<br />
=== What Graphics Cards work with VTK ===<br />
Modern graphics cards that supports OpenGL 2.1 or better typically provide all the functionality that VTK needs. However, there is good deal of variability in results across OS platform and vendor's OpenGL implementation. NVidia cards and drivers work the best. Intel HD integrated graphics and ATI Radeon HD devices and drivers are known to have a few issues. Mesa3D OpenGL although claiming support for a wide range of devices is highly unstable and the overall buggy-ness of their implementation changes daily and by renderer. Mesa's llvmpipe drivers are expected to generally work well. If there's an issue with one of Mesa's renderer's one might be able to work around by exporting the environment variable LIBGL_ALWAYS_SOFTWARE=1. Information about which driver and renderer are being used by VTK, and its capabilities, may be displayed by running "ctest -R LoadOpenGL --verbose" in a terminal from the VTK build/install dir.<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
===== General =====<br />
VTK binary files are not compatible between 32-bit and 64-bit systems. For portability, use the default file type, ASCII, for vtkPolyDataWriter, etc. You may be able to write a binary file on a 64-bit system and read it back in.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
See [[Cocoa_VTK]] for details if you are having trouble getting keyboard events working.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is no. For more recent versions, certainly 5.6 and later, the answer is yes.<br />
<br />
You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. For example:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* vtkImageWindow, vtkImager, vtkTkImageWindowWidget and their subclasses have been removed to reduce duplicated code and enable interation in ImageWindows. Now people should use vtkRenderer and vtkRenderWindow instead. vtkImageViewer still works as a turn key image viewing class although it now uses vtkRenderWindow and vtkRenderer internally instead of vtkImageWindow and vtkImager.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* Event processing: Several new events to VTK were added (see vtkCommand.h). Also event processing can now be prioritized and aborted. This allows applications to manage who processes which events, and terminates the processing of a particular event if desired.<br />
<br />
* 3D Widgets: A new class vtkInteractorObserver was added to observe events on vtkRenderWindowInteractor. Using the new event processing infrastructure, multiple 3D widgets (subclasses of vtkInteractorObserver) can be used simultaneously to process interactions. Several new 3D widgets have been added including:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* New class: vtkInstantiator provides a means by which one can create an instance of a VTK class using only the name of the class as a string.<br />
<br />
* New class: vtkXMLParser provides a wrapper around the Expat XML parsing library. A new parser can be written by subclassing from vtkXMLParser and providing a few simple virtual method implementations.<br />
<br />
* TIFF reader is now implemented using libtiff, which makes it capable of reading almost all available TIFF formats. The libtiff is also available internally as vtktiff.<br />
<br />
* New method (all sub-classes of vtkObject): Added a virtual function called NewInstance to vtkTypeMacro. NewInstance creates and returns an object of the same type as the current one. It does not copy any properties. The returned pointer is of the same type as the pointer the method was invoked with. This method should replace all the MakeObject methods scattered through VTK.<br />
<br />
* vtkSetObject macro is depricated for use inside the VTK. It is still a valid construct in projects that use VTK. Instead use vtkCxxSetObjectMacro which does the same thing.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was released in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008. A bunch more release have happened since then.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# Modify existing image filters to use the new vtkImageIterator etc. Most simple filters have been modified to use ithe iterator in VTK 4.2. It would be nice to have some sort of efficient neighborhood iterators but so far we haven't come up with any.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* Make UnstructuredGrid more compact by removing the cell point count from the vtkCellArray. This will reduce the storage required by each cell by 4 bytes.<br />
#* Make vtkPolyData an empty subclass of vtkUnstructuredGrid. There are a number of good reasons for this but it is a tricky task and backwards compatibility needs to be maintained.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* you can still use the vtkTextMapper + vtkActor2D combination, but we would advise you to use a single vtkTextActor instead, this will give you maximum flexibility.<br />
* has 1 text prop: TextProperty, but although you have access to it, do not twwak it unless you are using vtkTextMapper with a vtkActor2D. In all other cases, use the text prop provided by the actor (see below).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* the X (or Y) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/YAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* the X (Y or Z) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/Y/ZAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
Since VTK 4.x all classes have been carefully inspected to only include the necessary headers, and do what is called 'forward declaration' for all other needed classes. Thus, when you compile your projects using a filter that takes as input a dataset and you are passing an imagedata: you need to explicitly include imagedata within your implementation file. This is true for all data types.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
VTK requires at least OpenGL 1.1. VTK currently (v6.1) makes use of up to OpenGL 2.1 and a handful of extensions. Currently (v6.1) VTK makes use of the compatibility context and is not OpenGL 3.0 core compliant (http://www.opengl.org/wiki/Core_And_Compatibility_in_Contexts). If a given algorithm requires an OpenGL version or extension greater than what's available on a given system then either a fallback algorithm will be employed, as in the case of depth peeling, or an error will be reported indicating the required extension could not be found. One can display information about the system's OpenGL implementation as seen by VTK through the LoadOpenGL ctest. From a terminal in VTK build dir run "ctest -R LoadOpenGL --verbose". This will dump various driver information and list the extensions that VTK can use.<br />
<br />
=== Terminology ===<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
==== Linux/Unix ====<br />
Two ways:<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
* vendor specific tool<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. [http://www.vtk.org/VTK/project/license.html]<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=56031VTK/FAQ2014-04-04T18:08:59Z<p>Martink: </p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk can be found and downloaded from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Is there a mailing list for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://open.cdash.org/index.php?project=VTK<br />
<br />
VTK uses CTest/CDash to perform builds, run tests, and generate dashboards. You<br />
can find more information about CDash at: http://cdash.org<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
because the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and Google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# The VTK 4.x CVS nightly/development distribution supports Tcl/Tk 8.4 as long as you use a release version of CMake > 1.4.5. Since VTK 4.2 will require CMake 1.6, the next release version will support Tcl/Tk 8.4.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# Bad triangles are present: e.g., triangles with duplicate vertices such as (1,2,1) or (100,100,112), or (57,57,57), and so on. Solution: use ''vtkCleanPolyData''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. <br />
<br />
=== What Graphics Cards work with VTK ===<br />
Modern graphics cards that supports OpenGL 2.1 or better typically provide all the functionality that VTK needs. However, there is good deal of variability in results across OS platform and vendor's OpenGL implementation. NVidia cards and drivers work the best. Intel HD integrated graphics and ATI Radeon HD devices and drivers are known to have a few issues. Mesa3D OpenGL although claiming support for a wide range of devices is highly unstable and the overall buggy-ness of their implementation changes daily and by renderer. Mesa's llvmpipe drivers are expected to generally work well. If there's an issue with one of Mesa's renderer's one might be able to work around by exporting the environment variable LIBGL_ALWAYS_SOFTWARE=1. Information about which driver and renderer are being used by VTK, and its capabilities, may be displayed by running "ctest -R LoadOpenGL --verbose" in a terminal from the VTK build/install dir.<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
===== General =====<br />
VTK binary files are not compatible between 32-bit and 64-bit systems. For portability, use the default file type, ASCII, for vtkPolyDataWriter, etc. You may be able to write a binary file on a 64-bit system and read it back in.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
See [[Cocoa_VTK]] for details if you are having trouble getting keyboard events working.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is no. For more recent versions, certainly 5.6 and later, the answer is yes.<br />
<br />
You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. For example:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* vtkImageWindow, vtkImager, vtkTkImageWindowWidget and their subclasses have been removed to reduce duplicated code and enable interation in ImageWindows. Now people should use vtkRenderer and vtkRenderWindow instead. vtkImageViewer still works as a turn key image viewing class although it now uses vtkRenderWindow and vtkRenderer internally instead of vtkImageWindow and vtkImager.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* Event processing: Several new events to VTK were added (see vtkCommand.h). Also event processing can now be prioritized and aborted. This allows applications to manage who processes which events, and terminates the processing of a particular event if desired.<br />
<br />
* 3D Widgets: A new class vtkInteractorObserver was added to observe events on vtkRenderWindowInteractor. Using the new event processing infrastructure, multiple 3D widgets (subclasses of vtkInteractorObserver) can be used simultaneously to process interactions. Several new 3D widgets have been added including:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* New class: vtkInstantiator provides a means by which one can create an instance of a VTK class using only the name of the class as a string.<br />
<br />
* New class: vtkXMLParser provides a wrapper around the Expat XML parsing library. A new parser can be written by subclassing from vtkXMLParser and providing a few simple virtual method implementations.<br />
<br />
* TIFF reader is now implemented using libtiff, which makes it capable of reading almost all available TIFF formats. The libtiff is also available internally as vtktiff.<br />
<br />
* New method (all sub-classes of vtkObject): Added a virtual function called NewInstance to vtkTypeMacro. NewInstance creates and returns an object of the same type as the current one. It does not copy any properties. The returned pointer is of the same type as the pointer the method was invoked with. This method should replace all the MakeObject methods scattered through VTK.<br />
<br />
* vtkSetObject macro is depricated for use inside the VTK. It is still a valid construct in projects that use VTK. Instead use vtkCxxSetObjectMacro which does the same thing.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was released in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008. A bunch more release have happened since then.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# Modify existing image filters to use the new vtkImageIterator etc. Most simple filters have been modified to use ithe iterator in VTK 4.2. It would be nice to have some sort of efficient neighborhood iterators but so far we haven't come up with any.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* Make UnstructuredGrid more compact by removing the cell point count from the vtkCellArray. This will reduce the storage required by each cell by 4 bytes.<br />
#* Make vtkPolyData an empty subclass of vtkUnstructuredGrid. There are a number of good reasons for this but it is a tricky task and backwards compatibility needs to be maintained.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* you can still use the vtkTextMapper + vtkActor2D combination, but we would advise you to use a single vtkTextActor instead, this will give you maximum flexibility.<br />
* has 1 text prop: TextProperty, but although you have access to it, do not twwak it unless you are using vtkTextMapper with a vtkActor2D. In all other cases, use the text prop provided by the actor (see below).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* the X (or Y) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/YAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* the X (Y or Z) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/Y/ZAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
Since VTK 4.x all classes have been carefully inspected to only include the necessary headers, and do what is called 'forward declaration' for all other needed classes. Thus, when you compile your projects using a filter that takes as input a dataset and you are passing an imagedata: you need to explicitly include imagedata within your implementation file. This is true for all data types.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
VTK requires at least OpenGL 1.1. VTK currently (v6.1) makes use of up to OpenGL 2.1 and a handful of extensions. Currently (v6.1) VTK makes use of the compatibility context and is not OpenGL 3.0 core compliant (http://www.opengl.org/wiki/Core_And_Compatibility_in_Contexts). If a given algorithm requires an OpenGL version or extension greater than what's available on a given system then either a fallback algorithm will be employed, as in the case of depth peeling, or an error will be reported indicating the required extension could not be found. One can display information about the system's OpenGL implementation as seen by VTK through the LoadOpenGL ctest. From a terminal in VTK build dir run "ctest -R LoadOpenGL --verbose". This will dump various driver information and list the extensions that VTK can use.<br />
<br />
=== Terminology ===<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
==== Linux/Unix ====<br />
Two ways:<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
* vendor specific tool<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. [http://www.vtk.org/VTK/project/license.html]<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=VTK/FAQ&diff=56030VTK/FAQ2014-04-04T17:45:50Z<p>Martink: </p>
<hr />
<div>== General information and availability ==<br />
<br />
=== What is the Visualization Toolkit? ===<br />
<br />
The '''Visualization ToolKit (vtk)''' is a software system for 3D Computer<br />
Graphics and Visualization.<br />
<br />
VTK includes a textbook published by Kitware Inc. ([http://www.kitware.com/products/vtktextbook.html The Visualization<br />
Toolkit, An Object-Oriented Approach to 3D Graphics]),<br />
a C++ class library, and Tcl, Python and Java implementations based on<br />
the class library.<br />
<br />
For more information, see http://www.vtk.org and http://www.kitware.com.<br />
<br />
=== What is the current release? ===<br />
<br />
The current release of vtk can be found and downloaded from:<br />
<br />
http://www.vtk.org/VTK/resources/software.html<br />
<br />
Nightly development releases are available at:<br />
<br />
http://www.vtk.org/files/nightly<br />
<br />
=== Can I contribute code or bug fixes? ===<br />
<br />
We encourage people to contribute bug fixes as well as new contributions<br />
to the code. We will try to incorporate these into future releases so<br />
that the entire user community will benefit from them.<br />
<br />
See http://www.vtk.org/contribute.php for information on contributing to<br />
VTK.<br />
<br />
For some ideas take a look at some of the entries in the "Changes to the<br />
VTK API" FAQ section, for example: <br />
[[VTK_FAQ#Roadmap:_What_changes_are_being_considered_for_VTK|What changes are being considered for VTK]]<br />
<br />
We now have a bug tracker that allow keeping track of any bug you could find. See [http://www.vtk.org/Bug BugTracker].<br />
You'll need an email to report a bug.<br />
To improve the chance of a bug being fixed, do not hesitate to add as many details as possible, a demo sample code + sample data is always a good idea.<br />
Providing a patch almost guarantees that your patch will be incorporated into VTK.<br />
<br />
=== Is there a mailing list for VTK? ===<br />
<br />
There is a mailing list: vtkusers@vtk.org<br />
<br />
To subscribe or unsubscribe to the mailing list, go to:<br />
http://www.vtk.org/mailman/listinfo/vtkusers<br />
<br />
To search the list archives go to: http://www.kitware.com/search.html<br />
<br />
=== Is the VTK mailing list archived anywhere? ===<br />
<br />
The mailing list is archived at:<br />
http://www.vtk.org/pipermail/vtkusers/<br />
<br />
You can search the archive at: http://www.kitware.com/search.html<br />
<br />
=== Are answers for the exercises in the VTK book available? ===<br />
<br />
Not anymore.<br />
<br />
The answers to the exercises of the textbook used to be maintained by<br />
Martin Stoufer (kudos), and will be made available by Kitware in the<br />
near future.<br />
<br />
=== Is VTK regression tested on a regular basis? Can I help? ===<br />
<br />
Yes, it is.<br />
<br />
You can view the current regression test results at:<br />
http://open.cdash.org/index.php?project=VTK<br />
<br />
VTK uses CTest/CDash to perform builds, run tests, and generate dashboards. You<br />
can find more information about CDash at: http://cdash.org<br />
<br />
=== What's the best way to learn VTK? ===<br />
<br />
There are six things you might want to try:<br />
<br />
# Purchase the book [http://www.kitware.com/products/vtktextbook.html The Visualization Toolkit] from Kitware Inc.<br />
# Purchase the book [http://www.kitware.com/products/vtkguide.html VTK Users Guide] from Kitware Inc. <br />
# Check out some of the material at [[VTK Courses, Classes, Presentations]].<br />
# [http://www.vtk.org/get-software.php Download the source code and/or binaries] (available on Windows) and [[VTK/Examples|look at the examples]] (there are hundreds). <br />
# To learn the innards of VTK, you can attend a [http://www.kitware.com/products/proftrain.html#VTKCourse VTK course] or [http://www.kitware.com/products/proftrain.html sponsor a VTK course at your site] through Kitware. http://www.kitware.com/products/index.html<br />
# Buy Bill a beer and get him talking about VTK<br />
<br />
=== How should I ask questions on the mailing lists? ===<br />
<br />
The best online resource for this question is Eric S. Raymond's<br />
excellent guide on the topic titled [[http://www.catb.org/~esr/faqs/smart-questions.html How to ask questions the smart way]]. [[http://www.mikeash.com/getting_answers.html Getting Answers]] is a good starting point too.<br />
<br />
Please do read it and follow his advice. Thanks!<br />
<br />
Please also remember the following when you post your messages to the<br />
VTK mailing lists.<br />
<br />
* Mention the version of VTK you are using and the version of the compiler or scripting language you are using.<br />
<br />
* Mention your platform, OS and their versions.<br />
<br />
* Include hardware details if relevant.<br />
<br />
* Include all relevant error messages (appropriately trimmed of course).<br />
<br />
* The lists have a very large number of subscribers (in the thousands), so please keep messages to the point.<br />
<br />
* Use a sensible and descriptive subject line.<br />
<br />
* Do NOT post large data files or images to the list. Instead put them in your web page and mention the URLs.<br />
<br />
* Quote the messages you reply to appropriately. Remove unnecessary details.<br />
<br />
When asking a question or reporting a problem try to include a small<br />
example program that demonstrates the problem. Make sure that this<br />
example program is as small as you can make it, simple (and uses VTK<br />
alone), complete and demonstrates the problem adequately. Doing this<br />
will go a *long way* towards getting a quick and meaningful response.<br />
<br />
Sometimes you might not get any acceptable response. This happens<br />
because the others think the question has either been already answered<br />
elsewhere (the archives, FAQ and Google are your friends), or believe<br />
that you have not done enough homework to warrant their attention, or<br />
they don't know the answer or simply don't have the time to answer.<br />
Please do be patient and understanding. Most questions are answered by<br />
people volunteering their time to help you.<br />
<br />
Happy posting!<br />
<br />
=== How NOT to go about a programming assignment ===<br />
<br />
This is really a link you should read before posting to the mailing list. <br />
[This article is an attempt to show these irrational attitudes in an ironical way, <br />
intending to make our students aware of bad habits without admonishing them.]<br />
<br />
http://www.di.uniovi.es/~cernuda/noprog_ENG.html<br />
<br />
=== Where can I obtain test and sample datasets? ===<br />
<br />
See [[VTK Datasets|this page]] for details on downloading datasets that VTK can read.<br />
<br />
== Language bindings ==<br />
<br />
=== Are there bindings to languages other than Tcl? ===<br />
<br />
Aside from C++ (which it's written in) and Tcl, vtk is also bound into<br />
Java as of JDK 1.1 and Python 1.5, 1.6 and 2.X. All of the<br />
Tcl/Java/Python wrapper code is generated from some LEX and YACC code<br />
that parses our classes and extracts the required information to<br />
generate the wrapper code.<br />
<br />
=== What version of Tcl/Tk should I use with VTK? ===<br />
<br />
Currently we recommend that you use Tcl/Tk 8.2.3 with VTK. This is the<br />
best-supported version combination at this time.<br />
<br />
VTK has also been tested with Tcl/Tk 8.3.2 and works well.<br />
<br />
Tcl/Tk 8.3.4 has been tested to a limited extent but seems to have more<br />
memory leaks that Tcl 8.3.2 has.<br />
<br />
Tcl/Tk 8.4.x seems to work well with VTK too, but you might have to<br />
change a couple of configuration settings depending on the version of<br />
VTK you are using. Check the [[VTK_FAQ#Does_VTK_support_Tcl.2FTk_8.4_.3F|Does VTK support Tcl/Tk 8.4?]].<br />
<br />
=== Where can I find Python 2.x binaries? ===<br />
<br />
All of the Python binaries available on the kitware site are built for<br />
Python 1.5.2. This includes the official release VTK3.2 and the nightly<br />
builds (as at 2001-07-16).<br />
<br />
For Python 2.x binaries, you will have to compile your own from source.<br />
It is worth checking the mailing list archives for comments by others<br />
who have been through this process.<br />
<br />
There are some user-contributed binaries available at other sites. Check<br />
the mailing list archives for possible leads. Some win32 binaries for<br />
Python 2.1 are available at;<br />
<br />
http://basic.netmeg.net/godzilla/<br />
<br />
YMMV...<br />
<br />
=== Why do I get the Python error -- ValueError: method requires a VTK object? ===<br />
<br />
You just built VTK with Python support and everything went smoothly.<br />
After you install everything and try running a Python-VTK script you get<br />
a traceback with this error:<br />
<br />
ValueError: method requires a VTK object.<br />
<br />
This error occurs if you have two copies of the VTK libraries on your<br />
system. These copies need not be in your linkers path. The VTK libraries<br />
are usually built with an rpath flag (under *nix). This is necessary to<br />
be able to test the build in place. When you install VTK into another<br />
directory in your linkers path and then run a Python script the Python<br />
modules remember the old path and load the libraries in the build<br />
directory as well. This triggers the above error since the object you<br />
passed the method was instantiated from the other copy.<br />
<br />
So how do you fix it? The easiest solution is to simply delete the copy<br />
of the libraries inside your build directory or move the build directory<br />
to another place. For example, if you build the libraries in VTK/bin<br />
then move VTK/bin to VTK/bin1 or remove all the VTK/bin/*.so files. The<br />
error should no longer occur.<br />
<br />
Another way to fix the error is to turn the CMAKE_SKIP_RPATH boolean to<br />
ON in your CMakeCache.txt file and then rebuild VTK. You shouldn't have<br />
to rebuild all of VTK, just delete the libraries (*.so files) and then<br />
re-run cmake and make. The only trouble with this approach is that you<br />
cannot have BUILD_TESTING to ON when you do this.<br />
<br />
Alternatively, starting with recent VTK CVS versions (post Dec. 6, 2002)<br />
and with VTK versions greater than 4.1 (i.e. 4.2 and beyond) there is a<br />
special VTK-Python interpreter built as part of VTK called 'vtkpython'<br />
that should eliminate this problem. Simply use vtkpython in place of the<br />
usual python interpreter when you use VTK-Python scripts and the problem<br />
should not occur. This is because vtkpython uses the libraries inside<br />
the build directory.<br />
<br />
2002 by Prabhu Ramachandran<br />
<br />
=== Does VTK support Tcl/Tk 8.4 ? ===<br />
<br />
Short answer: yes, but it might require some adjustments, depending on<br />
the VTK and CMake versions you are using.<br />
<br />
# The VTK 4.x CVS nightly/development distribution supports Tcl/Tk 8.4 as long as you use a release version of CMake > 1.4.5. Since VTK 4.2 will require CMake 1.6, the next release version will support Tcl/Tk 8.4.<br />
# The VTK 4.0 release distribution does not support Tcl/Tk 8.4 out-of-the-box.<br />
<br />
In either cases, the following solutions will adress the problem. This<br />
basically involves setting two definition symbols that will make Tcl/Tk<br />
8.4 backward compatible with previous versions of Tcl/Tk (i.e. discard<br />
the "const correctness" and Tk_PhotoPutBlock compositing rule features) :<br />
<br />
a) Edit your C/C++ flags:<br />
<br />
Run your favorite CMake cache editor (i.e. CMakeSetup, or ccmake),<br />
display the advanced values and add the USE_NON_CONST and<br />
USE_COMPOSITELESS_PHOTO_PUT_BLOCK definition symbols to the end of any<br />
of the following CMake variables (if they exist): CMAKE_CXX_FLAGS,<br />
CMAKE_C_FLAGS.<br />
<br />
Example: On Unix your CMAKE_CXX_FLAGS will probably look like:<br />
<br />
-g -O2 -DUSE_NON_CONST -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
On Windows (Microsoft MSDev nmake mode):<br />
<br />
/W3 /Zm1000 /GX /GR /YX /DUSE_NON_CONST /DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
<br />
b) or a more intrusive solution:<br />
<br />
Edit the top VTK/CMakeList.txt file and the following lines add '''at the<br />
top''' of this file:<br />
<br />
ADD_DEFINITIONS(<br />
-DUSE_NON_CONST<br />
-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK<br />
)<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.NoClassDefFoundError: vtk/vtkSomeClassName"? ===<br />
The file '''vtk.jar''' is not in your CLASSPATH in your execution environment.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get "java.lang.UnsatisfiedLinkError: no vtkSomeLibraryName"? ===<br />
Some or all of the library (e.g., dll) files cannot be found. Make sure the files exist and that the PATH environment variable of your execution environment points to them.<br />
<br />
<br />
=== When I try to run my program with Java-wrapped VTK, why do I get Exception in thread "main" java.lang.UnsatisfiedLinkError: GetOutput_2 at vtk.vtkPolyDataAlgorithm.GetOutput_2(Native Method) ? ===<br />
<br />
== Using VTK ==<br />
<br />
=== The C++ compiler cannot convert some pointer type to another pointer type in my little program ===<br />
<br />
For instance, the C++ compiler cannot convert a <b><tt>vtkDataSet *</tt></b> type to a <b><tt>vtkImageData *</tt></b> type.<br />
<br />
It means the compiler does not know the relationship between a <b><tt>vtkDataSet</tt></b> and a <b><tt>vtkImageData</tt></b>. This relationship is actually inheritance: <b><tt>vtkImageData</tt></b> is a subclass of <b><tt>vtkDataSet</tt></b>. The only way for the compiler to know this relationship is to include the header file of the subclass, that is:<br />
<br />
#include "vtkImageData.h"<br />
<br />
If you wonder why the compiler did not complain about an unknown type, it is because somewhere (probably in a filter header file) there is a forward class declaration, like:<br />
<br />
class vtkImageData;<br />
<br />
=== Accessing a pointer in Python ===<br />
<br />
If you use VTK code with Python and need to pass some VTK data onto them, there are 2 approaches to wrap your code:<br />
# first, you can use the VTK wrapper (already used for the wrapping of VTK code)<br />
# you can use SWIG, which results in a light-weight module.<br />
<br />
In the second case, you will need to convert some VTK data, say a vtkPolyData, to a void pointer (no, it is not sufficient to just pass the object). For that, you can use the __this__ member variable in Python for the VTK data - see mailing archives:<br />
<br />
* [http://public.kitware.com/pipermail/vtkusers/2003-October/070054.html vtk, Python and SWIG - 'state of the union']<br />
<br />
=== What object/filter should I use to do ??? ===<br />
<br />
Frequently when starting out with a large visualization system people<br />
are not sure what object to use to achieve a desired effect.<br />
<br />
The most up-to-date information can be found in the VTK User's Guide<br />
(http://www.kitware.com/products/vtkguide.html).<br />
<br />
Alternative sources for information are the appendix of the book which<br />
has nice one line descriptions of what the different objects do and the<br />
VTK man pages (http://www.vtk.org/doc/nightly/html/classes.html).<br />
<br />
Additionally, the VTK man pages feature a "Related" section that provide<br />
links from each class to all the examples or tests using that class<br />
(http://www.vtk.org/doc/nightly/html/pages.html). This information is<br />
also provided in each class man page under the "Tests" or "Examples"<br />
sub-section.<br />
<br />
Some useful books are listed at http://www.vtk.org/buy-books.php<br />
<br />
=== What 3D file formats can VTK import and export? ===<br />
<br />
The following table identifies the file formats that VTK can read and<br />
write. Importer and Exporter classes move full scene information into or<br />
out of VTK. Reader and Writer classes move just geometry.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! File Format !! Read !! Write<br />
|-<br />
| 3D Studio || vtk3DSImporter || <br />
|-<br />
| AVS "UCD" format || vtkAVSucdReader || <br />
|-<br />
| Movie BYU || vtkBYUReader || vtkBYUWriter<br />
|-<br />
| Renderman || || vtkRIBExporter<br />
|-<br />
| Open Inventor 2.0 || || vtkIVExporter/vtkIVWriter<br />
|-<br />
| CAD STL || vtkSTLReader || vtkSTLWriter<br />
|-<br />
| Fluent GAMBIT ASCII || vtkGAMBITReader || <br />
|-<br />
| Unigraphics Facet Files || vtkUGFacetReader || <br />
|-<br />
| Marching Cubes || vtkMCubesReader || vtkMCubesWriter<br />
|-<br />
| Wavefront OBJ || || vtkOBJExporter<br />
|-<br />
| VRML 2.0 || || vtkVRMLExporter<br />
|-<br />
| VTK Structured Grid &dagger; || vtkStructuredGridReader || vtkStructuredWriter<br />
|-<br />
| VTK Poly Data &dagger; || vtkPolyDataReader || vtkPolyDataWriter<br />
|-<br />
| PLOT3D || vtkPLOT3DReader || <br />
|-<br />
| CGM || || vtkCGMWriter<br />
|-<br />
| OBJ || vtkOBJReader || <br />
|-<br />
| Particle || vtkParticleReader || <br />
|-<br />
| PDB || vtkPDBReader || <br />
|-<br />
| PLY || vtkPLYReader || vtkPLYWriter<br />
|-<br />
| Gaussian || vtkGaussianCubeReader || <br />
|-<br />
| Facet || vtkFacetReader || vtkFacetWriter<br />
|-<br />
| XYZ || vtkXYZMolReader || <br />
|-<br />
| Ensight &Dagger; || vtkGenericEnSightReader || <br />
|}<br />
<br />
&dagger; See the books [http://www.kitware.com/products/vtktextbook.html The<br />
Visualization Toolkit, An Object-Oriented Approach to 3D Graphics] or<br />
[http://www.kitware.com/products/vtkguide.html the User's Guide] for details<br />
about structured grid and poly data file formats.<br />
<br />
&Dagger; The class vtkGenericEnSightReader allows the user to read an EnSight<br />
data set without a priori knowledge of what type of EnSight data set it<br />
is (among vtkEnSight6BinaryReader, vtkEnSight6Reader,<br />
vtkEnSightGoldBinaryReader, vtkEnSightGoldReader,<br />
vtkEnSightMasterServerReader, vtkEnSightReader).<br />
<br />
For any other file format you may want to search for a converter to a<br />
known VTK file format, more info on:<br />
http://www.tech-edv.co.at/lunix/UTILlinks.html<br />
<br />
=== Why can't I find vtktcl (vtktcl.c)? ===<br />
<br />
In versions of VTK prior to 4.0 VTK Tcl scripts would require a:<br />
<br />
catch {load vtktcl} <br />
<br />
so that they could be executed directly from wish. In VTK 4.0 the<br />
correct mechanism is to use:<br />
<br />
package require vtk<br />
<br />
For people using versions earlier than 4.0, vtktcl is a shared library<br />
that is built only on the PC. Most examples used the "catch" notation so<br />
that they will work on UNIX and on the PC. On UNIX you must use the vtk<br />
executable/shell which should be in vtk/tcl/vtk.<br />
<br />
=== Why does this filter not produce any output? eg. GetPoints()==0 ===<br />
<br />
This is a very common question for VTK users. VTK uses a pipeline mechanism for rendering, which has multiple benefits, including the fact that filters that aren't used don't get called. This means that when you call a function such as x->GetOutput()->GetPoints() this will return 0 if the filter has not yet been executed. Just call x->Update() beforehand to make the pipeline update everything up to that point and it should work. -timh<br />
<br />
=== Problems with vtkDecimate and vtkDecimatePro ===<br />
<br />
''vtkDecimate'' and ''vtkDecimatePro'' have been tested fairly heavily so<br />
all known bugs have been removed. However, there are three situations<br />
where you can encounter weird behavior:<br />
<br />
# The mesh is not all triangles. Solution: use ''vtkTriangleFilter'' to triangulate polygons.<br />
# The mesh consists of independent triangles (i.e., not joined at vertices - no decimation occurs). Solution: use ''vtkCleanPolyData'' to link triangles.<br />
# Bad triangles are present: e.g., triangles with duplicate vertices such as (1,2,1) or (100,100,112), or (57,57,57), and so on. Solution: use ''vtkCleanPolyData''.<br />
<br />
=== How can I read DICOM files ? ===<br />
<br />
Starting with VTK 4.4, you can use the [http://www.vtk.org/doc/nightly/html/classvtkDICOMImageReader.html vtkDICOMImageReader class] to read DICOM files. Note however that DICOM is a huge protocol, and vtkDICOMImageReader is not able to read every DICOM file out there. If it does not meet your needs, we suggest you look for an existing converter before coding your own. Some of them are listed in the [http://www.dclunie.com/medical-image-faq/html/part8.html The Medical Image Format FAQ (Part 8)].<br />
<br />
==== GDCM ====<br />
<br />
For a more elaborate DICOM library that supports more image format, you might try [http://gdcm.sourceforge.net GDCM].<br />
Specifically: [http://gdcm.sourceforge.net/html/classvtkGDCMImageReader.html vtkGDCMImageReader] & [http://gdcm.sourceforge.net/html/classvtkGDCMImageWriter.html vtkGDCMImageWriter]<br />
<br />
Grassroots DiCoM is a C++ library for DICOM medical files. It is automatically wrapped to python/C#/Java (using swig). It supports RAW,JPEG (lossy/lossless),J2K,JPEG-LS,RLE and deflated. It also comes with DICOM Part 3,6 & 7 of the standard as XML files.<br />
<br />
If GDCM is too complex to integrate in your environment you can also consider simply using the command line converter: [http://apps.sourceforge.net/mediawiki/gdcm/index.php?title=Gdcmconv gdcmconv] to convert an unsupported DICOM file into something that vtkDICOMImageReader, can support. Typically you would want:<br />
<br />
gdcmconv --raw compressed_input.dcom uncompressed_output.dcom<br />
<br />
==== dicom2 ====<br />
<br />
Sebastien BARRE wrote a free DICOM converter, named dicom2, that can be<br />
used to convert medical images to raw format. This tool is a command<br />
line program and does not provide any GUI at the moment.<br />
http://dicom2.barre.nom.fr/<br />
<br />
There is a special section dedicated to the VTK:<br />
http://dicom2.barre.nom.fr/how-to.html, then "Convert to raw (vtk)"<br />
<br />
The following page also provide links to several other DICOM converters:<br />
http://www.barre.nom.fr/medical/samples/index.html#links<br />
<br />
==== vtkVolume16Reader ====<br />
<br />
When searching the vtkusers mailing list a lot of posts are still using vtkVolume16Reader to read in DICOM file. It will works in the following case:<br />
* You know the dimension (cols & rows) of your image<br />
* You know the spacing of your image<br />
* You know the pixel type (pixel type & #components) of your image<br />
* You know Pixel Data (7fe0,0010) is the last element in the image<br />
* You know Pixel Data (7fe0,0010) was sent in uncompressed format (not encapsulated)<br />
<br />
All those requirements are a stronger set of requirements than vtkDICOMImageReader, therefore it is encourage to use vtkDICOMImageReader instead.<br />
<br />
==== The spacing in my DICOM files are wrong ====<br />
<br />
Image Position (Patient) (0020,0032) is the only attribute that can be relied on to determine the "reconstruction interval" or "space between the center of slices".<br />
<br />
If the distance between Image Position (Patient) (0020,0032) of two parallel slices along the normal to Image Orientation (Patient) (0020,0037) is not the same as whatever happens to be in the DICOM Spacing Between Slices (0018,0088) attribute, then (0018,0088) is incorrect, without question<br />
<br />
This is a known bug in some scanners.<br />
<br />
When Slice Thickness (0018,0050) + Spacing Between Slices (0018,0088) equals the computed reconstruction interval, then chances are the modality implementor has made the obvious mistake of misinterpreting the definition of<br />
(0018,0088) to mean the distance between edges (gap) rather than the distance between centers.<br />
<br />
Further, one should never use Slice Location (0020,1041) either, an optional and purely annotative attribute, though chances are that the distance between the Slice Location (0020,1041) values of two slices will match the distance along the<br />
normal to the orientation derived from the position.<br />
<br />
The GDCM library simply discard any information present in the (0018,0088) tag and instead recompute the spacing by computing the distance in between two consecutive slices (along the normal).<br />
<br />
GDCM 1.x:<br />
typedef std::vector<gdcm::File *> FileList;<br />
FileList l;<br />
gdcm::SerieHelper sh;<br />
sh.OrderFileList(l); // calls ImagePositionPatientOrdering()<br />
zspacing = sh.GetZSpacing();<br />
<br />
GDCM 2.x:<br />
IPPSorter ipp;<br />
ipp.Sort( filenames );<br />
zspacing = ipp.GetZSpacing();<br />
<br />
=== How to handle large data sets in VTK ===<br />
<br />
One of the challenges in VTK is to efficiently handle large datasets. By<br />
default VTK is tuned towards smaller datasets. For large datasets there<br />
are a couple of changes you can make that should yield a much smaller<br />
memory footprint (less swapping) and also improve rendering performance.<br />
The solution is to:<br />
<br />
# Use ReleaseDataFlag,<br />
# Turn on ImmediateModeRendering<br />
# Use triangle strips via vtkStripper<br />
# Use a different filter or mapper<br />
<br />
Each of these will be discussed below.<br />
<br />
==== Using ReleaseDataFlag ====<br />
<br />
By default VTK keeps a copy of all intermediate results between filters<br />
in a pipeline. For a pipeline with five filters this can result in<br />
having six copies of the data in memory at once. This can be controlled<br />
using ReleaseDataFlag and GlobalReleaseDataFlag. If ReleaseDataFlag is<br />
set to one on a data object, then once a filter has finished using that<br />
data object, it will release its memory. Likewise, if<br />
GlobalReleaseDataFlag is set on ANY data object, all data objects will<br />
release their memory once their dependent filter has finished executing.<br />
For example in Tcl and C++<br />
<br />
# Tcl<br />
vtkPolyDataReader reader<br />
[reader GetOutput] ReleaseDataFlagOn<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->GetOutput()->GlobalReleaseDataFlagOn();<br />
<br />
While turning on the ReleaseDataFlag will reduce your memory footprint,<br />
the disadvantage is that none of the intermediate results are kept in<br />
memory. So if you interactively change a parameter of a filter (such as<br />
the isosurface value), all the filters will have to re-execute to<br />
produce the new result. When the intermediate results are stored in<br />
memory, only the downstream filters would have to re-execute.<br />
<br />
One hint for good interactive performance. If only one stage of the<br />
pipeline can have its parameters changed interactively (such as the<br />
target reduction in a decimation filter), only retain the data just<br />
prior to that step (which is the default) and turn ReleaseDataFlag on<br />
for all other steps.<br />
<br />
==== Use ImmediateModeRendering ====<br />
<br />
By default, VTK uses OpenGL display lists which results in another copy<br />
of the data being stored in memory. For most large datasets you will be<br />
better off saving memory by not using display lists. You can turn off<br />
display lists by turning on ImmediateModeRendering. This can be<br />
controlled on a mapper by mapper basis using ImmediateModeRendering, or<br />
globally for all mappers in a process by using<br />
GlobalImmediateModeRendering. For example:<br />
<br />
# Tcl<br />
vtkPolyDataMapper mapper<br />
mapper ImmediateModeRenderingOn<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
<br />
or<br />
<br />
// C++<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->GlobalImmediateModeRenderingOn();<br />
<br />
The disadvantage to using ImmediateModeRendering is that if memory is<br />
not a problem, your rendering rates will typically be slower with<br />
ImmediateModeRendering turned on.<br />
<br />
==== Use triangle strips via vtkStripper. ====<br />
<br />
Most filters in VTK produce independent triangles or polygons which are<br />
not the most compact or efficient to render. To create triangle strips<br />
from polydata you can first use vtkTriangleFilter to convert any<br />
polygons to triangles (not required if you only have triangles to start<br />
with) then run it through a vtkStipper to convert the triangles into<br />
triangle strips. For example in C++<br />
<br />
vtkPolyDataReader *reader = vtkPolyDataReader::New();<br />
reader->SetFileName("yourdatafile.vtk");<br />
reader->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkTriangleFilter *tris = vtkTriangleFilter::New();<br />
tris->SetInput(reader->GetOutput());<br />
tris->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkStripper *strip = vtkStripper::New();<br />
strip->SetInput(tris->GetOutput());<br />
strip->GetOutput()->ReleaseDataFlagOn();<br />
<br />
vtkPolyDataMapper *mapper = vtkPolyDataMapper::New();<br />
mapper->ImmediateModeRenderingOn();<br />
mapper->SetInput(tris->GetOutput());<br />
<br />
The only disadvantage to using triangle strips is that they require time<br />
to compute, so if your data is changing every time you render, it could<br />
actually be slower.<br />
<br />
==== Use a different filter or mapper ====<br />
<br />
This is a tough issue. In VTK there are typically a couple of ways to<br />
solve any problem. For example an image can be rendered as a polygon for<br />
each pixel, or it can be rendered as a single polygon with a texture map<br />
on it. For almost all cases the second approach will be much faster than<br />
the first event though VTK supports both. There isn't a single good<br />
answer for how to find the best approach. If you suspect that it is<br />
running more slowly than it should, try posting to the mailing list or<br />
looking for other ways to achieve the same result.<br />
<br />
=== VTK is slow, what is wrong? ===<br />
<br />
We have heard people say that VTK is really slow. In many of these<br />
cases, changing a few parameters can make a huge difference in performance.<br />
<br />
If you find that VTK is slower than other visualization systems running<br />
the same problem first take a look at the FAQ section dealing with large<br />
data: [[VTK_FAQ#How_to_handle_large_data_sets_in_VTK|How to handle large data sets in VTK]]. Many of its suggestions<br />
will improve VTK's performance significantly for many datasets.<br />
<br />
If you still find VTK slow, please let us know and send us an example<br />
(to mailto:kitware@kitware.com). In the past there<br />
have been some filters that simply were not written to be fast. When we<br />
come across one of these we frequently can make minor changes to the<br />
filter that will make it run much more quickly. In fact many changes in<br />
the past couple years have been this type of performance improvement.<br />
<br />
=== Is VTK thread-safe ? ===<br />
<br />
The short answer is no.<br />
<br />
Many VTK sources and filters cache information and will not perform as<br />
expected when used in multiple threads. When writing a multithreaded<br />
filter, the developer has to be very careful about how she accesses data.<br />
<br />
For example, GetXXX() methods which return a pointer should only be used<br />
to read. If the pointer returned by these methods are used to change<br />
data in multiple threads (without mutex locks), the result will most<br />
probably be wrong and unpredictable. In many cases, there are<br />
alternative methods which copy the data referred by the pointer. For<br />
example:<br />
<br />
float* vtkDataArray::GetTuple(const vtkIdType i);<br />
<br />
is thread-safe only for reading whereas:<br />
<br />
void vtkDataArray::GetTuple (const vtkIdType i, float * tuple);<br />
<br />
copies the requested tuple and is thread safe even if tuple is modified<br />
afterwards (as long as the same pointer is not passed as the argument<br />
tuple simultaneously by different threads).<br />
<br />
Unfortunately, only very few methods are clearly marked as<br />
thread-(un)safe and, in many situations, the developer has to dig into<br />
the source code to figure out whether an accessor is thread safe or not.<br />
<br />
''vtkDataSet'' and most of it's sub-classes are well documented and almost<br />
all methods are marked thread-safe or not thread-safe. This might be a<br />
good place to start. Most of the filters in imaging and some filters in<br />
graphics (like ''vtkStreamer'') are good examples of how a multi-threaded<br />
filter can be written in VTK.<br />
<br />
However, if you are not interested in developing multithreaded filters<br />
but want to process some data in parallel using the same (or similar)<br />
pipeline, your job is much easier. To do this, create a different copy<br />
of the pipeline on each thread and execute them in parallel on a<br />
different piece of the data. This is best accomplished by using<br />
''vtkThreadedController'' (instead of ''vtkMultiThreader''). See the<br />
documentation of ''vtkMultiProcessController'' and ''vtkThreadedController''<br />
and the examples in the parallel directory for details on how this can<br />
be done.<br />
<br />
Also, note that most of the OpenGL libraries are not thread-safe.<br />
Therefore, if you are rendering to multiple render windows from<br />
different threads, you are likely to get in trouble, even if you have<br />
mutex locks around the render calls.<br />
<br />
=== Can I use STL with VTK? ===<br />
<br />
As of VTK version 4.2, you can use the STL.<br />
However, see the [[VTK Coding Standards]] for limitations.<br />
Here's an example (from vtkInterpolateVelocityField):<br />
<br />
In the .h file (the PIMPL) forward declare<br />
<br />
class vtkInterpolatedVelocityFieldDataSetsType;<br />
//<br />
class VTK_COMMON_EXPORT vtkInterpolatedVelocityField : public vtkFunctionSet<br />
{<br />
private:<br />
vtkInterpolatedVelocityFieldDataSetsType* DataSets;<br />
};<br />
<br />
In the .cxx file define the class (here deriving from the STL vector<br />
container)<br />
<br />
# include <vtkstd/vector><br />
typedef vtkstd::vector< vtkSmartPointer<vtkDataSet> > DataSetsTypeBase;<br />
class vtkInterpolatedVelocityFieldDataSetsType: public DataSetsTypeBase<br />
{};<br />
<br />
In the .cxx file construct and destruct the class:<br />
<br />
vtkInterpolatedVelocityField::vtkInterpolatedVelocityField()<br />
{<br />
this->DataSets = new vtkInterpolatedVelocityFieldDataSetsType;<br />
}<br />
vtkInterpolatedVelocityField::~vtkInterpolatedVelocityField()<br />
{<br />
delete this->DataSets;<br />
}<br />
<br />
And in the .cxx file use the container as you would any STL container:<br />
<br />
for ( DataSetsTypeBase::iterator i = this->DataSets->begin();<br />
i != this->DataSets->end(); ++i)<br />
{<br />
ds = i->GetPointer();<br />
....<br />
}<br />
<br />
=== What image file formats can VTK read and write? ===<br />
<br />
The following table identifies the image file formats that VTK can read<br />
and write.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|- bgcolor="#abcdef"<br />
! Image File !! Read !! Write<br />
|-<br />
| AVI || || vtkAVIWriter<br />
|-<br />
| Bitmap || vtkBMPReader || vtkBMPWriter<br />
|-<br />
| Digital Elevation Model (DEM) || vtkDEMReader || <br />
|-<br />
| DICOM || vtkDICOMImageReader || <br />
|-<br />
| GE Signal || vtkGESignaReader || <br />
|-<br />
| JPEG || vtkJPEGReader || vtkJPEGWriter<br />
|-<br />
| FFMPEG || || vtkFFMPEGWriter<br />
|-<br />
| MINC (1.1) || vtkMINCImageReader || vtkMINCImageWriter<br />
|-<br />
| Binary UNC meta image data || vtkMetaImageReader || vtkMetaImageWriter<br />
|-<br />
| PNG || vtkPNGReader || vtkPNGWriter<br />
|-<br />
| PNM || vtkPNMReader || vtkPNMWriter<br />
|-<br />
| PostScript || || vtkPostScriptWriter <br />
|-<br />
| SLC || vtkSLCReader || <br />
|-<br />
| TIFF || vtkTIFFReader || vtkTIFFWriter<br />
|-<br />
| RAW files &dagger; || vtkImageReader, vtkVolumeReader || <br />
|}<br />
<br />
&dagger; A typical example of use is:<br />
<br />
# Image pipeline<br />
reader = vtkImageReader()<br />
reader.SetDataByteOrderToBigEndian()<br />
reader.SetDataExtent(0,511,0,511,0,511)<br />
reader.SetFilePrefix("Ser397")<br />
reader.SetFilePattern("%s/I.%03d")<br />
reader.SetDataScalarTypeToUnsignedShort()<br />
reader.SetHeaderSize(5432)<br />
<br />
=== Printing an object. ===<br />
<br />
Sometimes when debugging you need to print an object to a string, either<br />
for logging purposes, or in the case of windows applications, to a window.<br />
<br />
Here is a way to do this:<br />
<br />
std::ostringstream os;<br />
//<br />
// "SomeVTKObject" could be, for example, <br />
// declared somewhere as: vtkCamera *SomeVTKObject;<br />
//<br />
SomeVTKObject->Print(os);<br />
vtkstd::string str = os.str();<br />
//<br />
// Process the string as you want<br />
<br />
=== Writing a simple CMakeLists.txt. ===<br />
<br />
If you get something that looks like:<br />
<br />
undefined reference to<br />
`__imp___ZN13vtkTIFFReader3NewEv'<br />
collect2: ld returned 1 exit status <br />
<br />
You certainly forgot to pass in a library to your executable. The easisest way is to use CMakeLists.txt file.<br />
<br />
For example the minimal project is:<br />
<br />
FIND_PACKAGE(VTK)<br />
IF (VTK_FOUND)<br />
INCLUDE (${VTK_USE_FILE})<br />
ENDIF (VTK_FOUND)<br />
ADD_EXECUTABLE(tiff tiff.cxx )<br />
TARGET_LINK_LIBRARIES (tiff<br />
vtkRendering<br />
)<br />
<br />
Since vtkRendering is link against all other vtk lib. Except if you are building VTK with Hybrid or Parallel in that case you need to explicitely specify which library you want to link against.<br />
<br />
=== Testing for VTK within a configure script ===<br />
<br />
VTK uses CMake as build tool but if you VTK-based application wants to use autoconf and/or automake, then you will find very useful an M4 macro file which detects from your configure script the presence/absence of VTK on the user system. VTK won't add such file into the official distribution but you can always write your own, as I did.<br />
Look in [[VTK_Autoconf]] page for more info.<br />
<br />
=== How do I get my C++ code editor to do VTK-style indentation? ===<br />
<br />
If you are writing code with VTK, you may want to follow the [[VTK Coding Standards]]. This is particularly important if you plan to contribute back to VTK. Most C++ code editors will help you with indenting, but the indenting may differ significantly from that prescribed by the [[VTK Coding Standards]]. Fortunately, most editors have enough options to allow you to change the indention enough to get at least close to the VTK-style indentation.<br />
<br />
Below is a list of C++ editors and some suggestions on getting the indentation VTK compliant. If you use a popular editor that is not listed here, please feel free to contribute.<br />
<br />
==== Microsoft Visual C++ .NET indentation ====<br />
<br />
Under the "Tools" menu, select "Options". Go to the options under "Text Editor" and then "C/C++". Click the "Tabs" options. Set "Indenting" to "Smart", "Indent Size" to 2, and select "Insert spaces". Click the "Formatting" options enable "Indent braces".<br />
<br />
This will make most of the indentation correct. However, it will indent all of the braces. In VTK classes, most of the braces are indented, but those starting a class, method, or function are typically flush left. You will have to correct this on your own.<br />
<br />
==== Emacs indentation ====<br />
<br />
Place the [[Elisp Code for VTK-Style C Indentation]] in your .emacs file.<br />
<br />
==== Vim indentation ====<br />
<br />
[[user talk:Andy|Andy Cedilnik]] has some information on following the VTK coding guidelines using vim. You may place the following in your <code>~/.vimrc</code> file<br />
set tabstop=2 " Tabs are two characters<br />
set shiftwidth=2 " Indents are two charactes too<br />
set expandtab " Do not use tabs<br />
set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1<br />
"Keep tabs in makefiles as they are significant:<br />
:autocmd BufRead,BufNewFile [Mm]akefile :set noexpandtab<br />
<br />
=== How to display transparent objects? ===<br />
(keywords: alpha, correct, depth, geometry, object, opacity, opaque, order, ordering, peel, peeling, sorting, translucent, transparent.)<br />
<br />
When opaque geometry is rendered, there is no need to sort it because the depth buffer (or z-buffer) is used and the sorting is done automatically by keeping the geometry closest to the viewpoint at<br />
a given pixel. (It is easy because it is a MAX/MIN calculation, not a real sorting).<br />
<br />
With translucent geometry the final color of a pixel is the contribution of all the geometry primitives visible through the pixel. The color of the pixel is the result of <b>a</b> blending operation between the colors of all visible primitives. Blending operations themselves are usually order-dependent (ie not commutative). That's why depth sorting is required. There are two ways to fix the ordering in VTK:<br />
<br />
*1. Append all your polygonal geometry with [http://www.vtk.org/doc/nightly/html/classvtkAppendPolyData.html vtkAppendPolyData] and pass it to [http://www.vtk.org/doc/nightly/html/classvtkDepthSortPolyData.html vtkDepthSortPolyData]. See this tcl [http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*/Hybrid/Testing/Tcl/depthSort.tcl?root=VTK&content-type=text/plain example]. Depth sorting is done per centroid of geometry primitives, not per pixel. For this reason it is not exact but it solves <b>most</b> of the ordering and gives result usually good enough.<br />
* 2. If the graphics card supports it, use "[[VTK/Depth_Peeling | depth peeling]]". It performs per pixel sorting (better result) but it is really slow.<br />
<br />
=== What's the deal with SetInput() vs. SetInputConnection()? ===<br />
(keywords: SetInput, SetInputConnection, vtkAlgorithm, algorithm, pipeline, source)<br />
<br />
In the transition from VTK 4 to VTK 5, the VTK pipeline executive was completely cleaned up and redesigned. The fundamental idea behind the new pipeline is that the "pipeline" should consist of a chain of "algorithm" objects.<br />
The algorithms are connected together with the familiar b->SetInputConnection(a->GetOutputPort()) methods.<br />
<br />
So how is this different from SetInput()/GetOutput()? The difference between an "OutputPort" and an "Output" is as follows:<br />
<br />
* OutputPort (''vtkAlgorithmOutput''): A trivial object that says "I am output port N of algorithm X" (usually N = 0).<br />
* Output (''subclass of vtkDataObject''): A container for data produced by any VTK code.<br />
<br />
The "OutputPort" method does not presuppose anything about what data (if any) will pass along the pipeline. It could simply signify that algorithm "a" must execute before algorithm "b". This provides enormous flexibility. Trust the VTK designers here, it's better to do things this way than to have the user grab the actual data object from the output of one algorithm and shove it into the input of another.<br />
<br />
However, any newcomer to VTK will quickly notice that the use of SetInputConnection() is not universal. The reason is this: only vtkAlgorithm objects can have a SetInputConnection() or GetOutputPort() method. Some objects that can take inputs are not derived from vtkAlgorithm. For example vtkImageActor is a vtkProp3D and therefore it cannot be a vtkAlgorithm (VTK never uses multiple inheritance). This is a case of an old VTK object that doesn't "fit" the new VTK 5 pipeline. However, the VTK developers did not want to throw away such useful classes when the pipeline was redesigned. Instead, such classes are still served by the backwards-compatible SetInput() method.<br />
<br />
So, use SetInputConnection() whenever you can, but if there is no SetInputConnection(), then go ahead and use SetInput(). There is nothing wrong with doing so. The new pipeline is backwards compatible with the old pipeline methods.<br />
<br />
== Platform-specific questions ==<br />
<br />
=== What platforms does vtk run on? ===<br />
<br />
VTK should compile and run on most versions of Unix, Linux, Windows, and Mac OS X. It has been tested on Suns, SGIs, HPs, Alphas, RS6000s and many Windows and Mac workstations.<br />
<br />
=== What Graphics Cards work with VTK ===<br />
Modern graphics cards that supports OpenGL 2.1 or better typically provide all the functionality that VTK needs. However, there is good deal of variability in results across OS platform and vendor's OpenGL implementation. NVidia cards and drivers work the best. Intel HD integrated graphics and ATI Radeon HD devices and drivers are known to have a few issues. Mesa3D OpenGL although claiming support for a wide range of devices is highly unstable and the overall buggy-ness of their implementation changes daily and by renderer. Mesa's llvmpipe drivers are expected to generally work well. If there's an issue with one of Mesa's renderer's one might be able to work around by exporting the environment variable LIBGL_ALWAYS_SOFTWARE=1. Information about which driver and renderer are being used by VTK, and its capabilities, may be displayed by running "ctest -R LoadOpenGL --verbose" in a terminal from the VTK build/install dir.<br />
<br />
=== How do I build the examples on the PC running Windows? ===<br />
<br />
Since building the C++ examples on the PC isn't all that easy, here are<br />
some instructions from Jack McInerney.<br />
<br />
Steps for creating a VTK C++ project 8/14/96<br />
<br />
This is based on what I learned creating a project to run the Mace<br />
example. These steps allowed me to successfully built and run this example.<br />
<br />
# Create a console project (File, New, then select Console application).<br />
# Add the files of interest to the project. (e.g., Mace.cxx)<br />
# Under Build, select Update all Dependencies. A long list of .hh files will show up under dependencies<br /> For this to work, Visual C++ needs to know where to look to find the include files. In my case they are at C:\VTK\VTK12SRC\INCLUDE. To tell Visual C++ to look there, go to Tools, Options. Select the tab Directories. Under the list for Include files add: C:\VTK\VTK12SRC\INCLUDE<br />
# Compile the file Mace.cxx. This will lead to many warnings about data possibly lost as double variables are converted to float variables. These can be gotten rid of by going to Build, Settings, and select the C++ tab. Under the General catagory, set Warning Level to 1* (instead of 3).<br />
# Before linking, some additional settings must be modified. Go to Build, Settings, and select the Link tab. In the General catagory, add the libraries opengl32.lib and glaux.lib to the Object/Library Modules. Put a space between each file name. Then select the C++ tab and the Category: Code Generation. Under Use Run-Time Library, select Debug Multithreaded DLL. Select OK to exit the dialog box. The above libraries are available from Microsoft's Web site at: http://www.microsoft.com/softlib/mslfiles/Opengl95.exe or ftp://ftp.microsoft.com/softlib/mslfiles/Opengl95.exe <br /> This is a self extracting archive which contains these files. Simply place them in your windows system directory.<br />
# Link the code by selecting Build, Build MaceProject.exe. I still get one warning when I do this, but it appears to be harmless<br /><br />
<br />
When you go to run the program, it will bomb out unless it can find 2<br />
DLLs: Opengl32.dll and Glu32.dll. These need to be located either in the<br />
project directory or the C:\WINDOWS directory. These files are supplied<br />
on the vtk CD-ROM (in the vtk\bin directory).<br />
<br />
=== How do I build the Java examples on the PC running Windows? ===<br />
One common issue building the examples is missing one or all of vtkPanel, vtkCanvas and AxesActor<br />
classes. For whatever reason these are not in the vtk.jar (at least for 4.2.2).<br />
But you can get them from the source distribution (just unzip the source and extract<br />
these needed .java files, and point your Java-compiler to them).<br />
<br />
Another common issue appears to be class loading dependency errors. Make sure the<br />
directory with the .dll files is in your classpath when you run (default location<br />
is C:\Program Files\vtk42\bin\). Yet this still seems insufficient for some of the<br />
libraries. One possible solution is to copy the Java awt.dll to this directory as<br />
well.<br />
<br />
=== 64-bit System Issues ===<br />
<br />
vtk builds on 64 bit systems, that is, systems where sizeof(void*) is 64 bits. However, parts of the vtk codebase are not 64 bit clean and so runtime problems are likely if that code is used.<br />
<br />
===== General =====<br />
VTK binary files are not compatible between 32-bit and 64-bit systems. For portability, use the default file type, ASCII, for vtkPolyDataWriter, etc. You may be able to write a binary file on a 64-bit system and read it back in.<br />
<br />
===== Mac OS X Specific =====<br />
Mac OS X 10.3 and earlier have no support for 64 bit. On Mac OS X 10.4, VTK cannot be built as 64 bit because it requires Carbon, Cocoa, or X11, none of which are available to 64 bit processes. On Mac OS X 10.5 and later, Cocoa is available to 64 bit processes, but Carbon is not. VTK is known to work well with 64 bit Cocoa on Mac OS X 10.5 and later.<br />
<br />
===== Windows Specific =====<br />
todo<br />
<br />
=== What size swap space should I use on a PC? ===<br />
<br />
Building vtk on the PC requires a significant amount of memory (at least<br />
when using Visual C++)... but the final product is nice and compact. To<br />
build vtk on the PC, we recommend setting the min/max swap space to at<br />
least 400MB/500MB (depending on how much RAM you have... the sum of RAM<br />
and swap space should be roughly 500+ MB).<br />
<br />
=== Are there any benchmarks of VTK and/or the hardware it runs on? ===<br />
<br />
Take a look at the "Simple Sphere Benchmark":<br />
<br />
http://www.barre.nom.fr/vtk/bench.html<br />
<br />
It is not a "real world" benchmark, but provide synthetic results<br />
comparing different hardware running VTK:<br />
<br />
http://purl.oclc.org/NET/rriv/vtk/sphere-bench<br />
<br />
=== Why is XtString undefined when using VTK+Python on Unix? ===<br />
<br />
This is a side effect of dynamic linking on (some?) Unix systems. It<br />
appears often on Linux with the Mesa libraries at least. The solution is<br />
to make sure your Mesa libraries are linked with the Xt library. One way<br />
to do this is to add "-lXt" to MESA_LIB in your user.make file.<br />
<br />
=== How do I get the Python bindings to work when building VTK with Borland C++? ===<br />
<br />
If you've built VTK with the freely downloadable Borland C++ 5.5 (or its<br />
commercial counterpart) and you're using the Python binaries from<br />
http://www.python.org/, you'll note that when you try to run a VTK<br />
Python example you get something similar to the following error message:<br />
<br />
from vtkCommonPython import * <br />
ImportError: dynamic module does not define init function<br />
(initvtkCommonPython)<br />
<br />
This is because BCC32 prepends an underscore ("_") to all exported<br />
functions, so (in this case) the vtkCommonPython.dll contains a symbol<br />
_initvtkCommonPython which Python does not find. All kits (e.g.<br />
Rendering, Filtering, Patented) will suffer from this problem.<br />
<br />
The solution is to create Borland module definition in the VTK binary<br />
(output) directory, in my case VTK/bin. You have to do this for all kits<br />
that you are planning to use in Python. Each .def file must have the<br />
same basename as the DLL, e.g. "vtkCommonPython.def" for<br />
vtkCommonPython.dll and it must be present at VTK link time. The def<br />
file contains an export alias, e.g.:<br />
<br />
EXPORTS<br />
initvtkCommonPython=_initvtkCommonPython<br />
<br />
The Borland compiler will create an underscore-less alias in the DLL<br />
file and Python will be able to load it as a module.<br />
<br />
=== How do I build Python bindings on AIX? ===<br />
<br />
There is a problem with dynamic loading on AIX. Old AIX did not have<br />
dlopen/dlsym, but they used load mechanism. Python still reflects this.<br />
VTK is however not compatible with the old load mechanism.<br />
<br />
The following patch to Python 2.2.2 makes python use dlopen/dlsym on AIX<br />
5 or greater.<br />
<br />
http://www.vtk.org/files/misc/python_aix.diff<br />
<br />
=== How to build VTK for offscreen rendering? ===<br />
<br />
See http://paraview.org/Wiki/ParaView_And_Mesa_3D.<br />
<br />
=== How to get keyboard events working on Mac OS X? ===<br />
<br />
See [[Cocoa_VTK]] for details if you are having trouble getting keyboard events working.<br />
<br />
=== Can VTK be built as a Universal Binary on Mac OS X? ===<br />
<br />
For VTK 5.0.4 and older, the short answer is no. For more recent versions, certainly 5.6 and later, the answer is yes.<br />
<br />
You need to set CMAKE_OSX_ARCHITECTURES to the architectures you want and CMAKE_OSX_SYSROOT to a Mac OS X SDK that supports Universal builds. For example:<br />
<br />
CMAKE_OSX_ARCHITECTURES=ppc;i386 <br />
CMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk<br />
<br />
=== How can I stop Java Swing or AWT components from flashing or bouncing between values? ===<br />
<br />
While not strictly a VTK problem, this comes up fairly often when using Java-wrapped VTK. Try the following two JRE arguments to stop the Swing/AWT components flashing:<br />
-Dsun.java2d.ddoffscreen=false -Dsun.java2d.gdiblit=false<br />
Note that these are classified as "unsupported properties," so may not work on all platform or installations (in particular, ddoffscreen refers to DirectDraw and, as such, is specific to Windows).<br />
<br />
=== How can a user process access more than 2 GB of ram in 32-bit Windows? ===<br />
<br />
By default on Windows, the most memory that a user process can access is 2 GB, no matter how much RAM you have installed in your system. With Windows XP Professional you can make it possible for a process to use up to 3 GB of memory by doing two things:<br />
<br />
1) Modify the boot parameters in boot.ini (on my 32 bit WinXP Pro machine, it's in: "C:\boot.ini") to tell the operating system that you want user processes to have access to up to 3GB of RAM (This is a really important file, and if you don't know what you are doing, stop reading this and go back to work!). This is done by adding the /3GB flag to the line of the file that tells the boot loader where the operating system is. My boot.ini file looks like:<br />
<br />
[boot loader]<br />
timeout=30<br />
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS<br />
[operating systems]<br />
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /3GB<br />
<br />
This is a very bad file to make mistakes on, so don't - it may be very difficult to repair your computer to boot if you mess up this file. There is a nice description of this in the Microsoft article <br />
[http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx Memory Support and Windows Operating Systems].<br />
<br />
2) The other thing that you need to do is make your executable LARGEADDRESSAWARE. Assuming that you have a Windows binary that you want to try this on, you can use the 'editbin' utility that comes with Visual Studio to change the setting of one bit (the IMAGE_FILE_LARGE_ADDRESS_AWARE bit) in the image header of the executable. For a program 'prog.exe' you can make the change by<br />
<br />
editbin /LARGEADDRESSAWARE prog.exe<br />
<br />
Of course, depending on how your program handles memory you might find that it crashes when you try to use the extra memory, but that's a separate issue. If you are compiling your program with a version of Visual Studio you should be able to find the switch to make your program /LARGEADDRESSAWARE.<br />
<br />
=== Shared builds of VTK and debugging QVTKWidget using Visual Studio ===<br />
<br />
Assuming that you have built a shared build of VTK and you may or may<br />
not have a set it up such that there is a path to the release version<br />
of VTK in your PATH statement.<br />
<br />
Then if you debug a project that is using QVTKWidget, you will come<br />
across a problem in that if you are debugging a debug version; the<br />
application depends upon the debug version of QVTK.dll which will<br />
depend upon QtGui4d.dll (among others) and load it. But, because the<br />
release version of QVTK.dll is in the path, QtGiu4.dll will also be<br />
loaded preventing the application from running. You will get a<br />
"QWidget: Must construct a QApplication before a QPaintDevice"<br />
message.<br />
<br />
The solution to this problem is to set the path to the correct build<br />
of VTK on the "'''Debugging'''" properties of your project. Right click on<br />
your project, bring up the properties dialog, and select "'''Debugging'''"<br />
from the list on the left. There should be an "'''Environment'''" line. You<br />
can add variables here using key=value pairs.<br />
For example, add the following line:<br />
PATH=<Path To VTK>\bin\$(OutDir);%PATH%<br />
You can then add the same line to other configurations, such as the release one, by selecting<br />
them from the top left drop down box labelled '''Configuration'''.<br />
<br />
$(OutDir) will be set by Visual Studio to either Debug or Release,<br />
depending upon what configuration you have selected. Make sure <br />
that ;%PATH% is appended so that Qt and other files can be appended <br />
to the PATH statement.<br />
<br />
<br />
== Changes to the VTK API ==<br />
<br />
=== What is the policy on Changes to the API ===<br />
<br />
Between patch releases maintain the API unless there is a really strong reason not to. <br />
<br />
Between regular releases maintain backwards compatibility to the API with prior releases of VTK when doing so does not increase the complexity or readability of the current VTK or when the benefits of breaking the API are negligible.<br />
<br />
Clearly these statements have a lot of wiggle room. For example in vtkLightKit BackLight and Headlight were used and released. Now BackLight and HeadLight might make more sense and probably will be easier for non-native English speakers, but is it worth breaking the API for it, probably not. Another factor is how long the API has been around and how widely used it is. These all indicate how painful it will be to change the API which is half of the cost/benefit decision.<br />
<br />
=== Change to vtkIdList::IsId() ===<br />
<br />
vtkIdList::IsId(int id) used to return a 0 or 1 to indicate whether the<br />
specified id is in the list. Now it returns -1 if the id is not in the<br />
list; or a non-negative number indicating the position in the list.<br />
<br />
=== Changes vtkEdgeTable ===<br />
<br />
vtkEdgeTable had two changes. The constructor now takes no arguments,<br />
and you use InitEdgeInsertion() to tell the class how many points are in<br />
the dataset. Also, IsEdge(p1,p2) now returns a -1 if the edge (defined<br />
by points p1,p2) is not defined. otherwise a non-negative integer value<br />
is returned.<br />
<br />
These changes were made to support the association of attributes with<br />
edges.<br />
<br />
=== Changes between VTK 4.2 and VTK 4.4 (and how to update) ===<br />
<br />
We have removed the CVS date, revision, and the language from the<br />
copyright on all the files. This information wasn't being used much and<br />
it created extra work for developers. For example you edit vtkObject.h<br />
rebuild all of VTK, check in you change, then you must rebuild all of<br />
VTK again because commiting the header file causes it to be changed by<br />
CVS (because the revision number changed) This change will also make it<br />
easier to compare different branches of VTK since these revision number<br />
differences will no longer show up. The CVS revision number is still in<br />
the cxx file in the RevisionMacro. You don't need to make any changes to<br />
your code for this.<br />
<br />
The DataArray classes now use a templated intermediate class to share<br />
their implementation. Again there is no need for you to make changes to<br />
your code.<br />
<br />
Legacy code has been removed. Specifically none of the old style<br />
callbacks are supported and observers should be used instead. So where<br />
you used a filter->SetStartMethod(myFunc) you should do a<br />
filter->AddObserver(vtkCommand::StartEvent,myCommand) Usually this will<br />
require you to create a small class for the observer.<br />
vtkImageOpenClose3D.cxx has an example of using an observer and there<br />
are a few other examples in VTK. If you switch to using Observers your<br />
code should also work with versions of VTK from 3.2 or later since the<br />
Observers have been in VTK since VTK 3.2.<br />
<br />
Many functions that previously took or returned float now take or return<br />
double. To change your code to work with VTK 4.4 or later you can just<br />
replace float with double for the appropriate calls and variables. If<br />
you want your code to work with both old and new versions of VTK you can<br />
use vtkFloatingPointType which is defined to be double in VTK 4.4 and<br />
later and it is float in vtk 4.2.5. In versions of VTK prior to 4.2.5<br />
you can use something like:<br />
<br />
#ifndef vtkFloatingPointType<br />
#define vtkFloatingPointType vtkFloatingPointType<br />
typedef float vtkFloatingPointType;<br />
#endif<br />
<br />
at the beginning of your code. That will set it to the correct value for<br />
all versions of VTK old and new.<br />
<br />
=== Use of New() and Delete() now enforced (vs. new & delete) ===<br />
<br />
Constructors and destructors in VTK are now protected. This means you<br />
can no longer use little "new" or "delete" to create VTK instances.<br />
You'll have to use the methods ::New() and ::Delete() (as has been<br />
standard practice for some time).<br />
<br />
The reason for this is to enforce the use of New() and Delete(). Not<br />
using New() and Delete() can lead to bad mojo, mainly reference counting<br />
problems or not taking advantage of special procedures incorporated into<br />
the New() method (e.g., selecting the appropriate hardware interface<br />
during instance creation time).<br />
<br />
If you've used New() and Delete() in your code, these changes will not<br />
affect you at all. If you're using little "new" or "delete", your code<br />
will no longer and compile and you'll have to switch to New() and Delete().<br />
<br />
=== Changes between VTK 4.4 and VTK 4.6 ===<br />
<br />
Collection Changes<br />
<br />
Collections have had some small changes (originally started by Chris<br />
Volpe) to better support reentrant iteration. Specifically all the<br />
collection have an InitTraversal(sit) and GetNextFoobar(sit) methods.<br />
(where Foobar is what the collection contains, for example<br />
GetNextActor(sit)) The argument to both of these methods is a<br />
vtkCollectionSimpleIterator. Most of the collection use in VTK has been<br />
modified to use these new methods. The advantage is that these new<br />
methods support having the same collection be iterated through in a<br />
reentrant safe manner. In the past this was not true and led to a number<br />
of problems. In the future for C++ class development please use this<br />
approach to iterating through a collection. These changes are fully<br />
backwards compatible and no old APIs were harmed in the making of these<br />
changes. So in summary, for the future, where you would have written:<br />
<br />
for (actors->InitTraversal();<br />
(actor = actors->GetNextActor());)<br />
<br />
you would now have:<br />
<br />
vtkCollectionSimpleIterator actorIt;<br />
for (actors->InitTraversal(actorIt);<br />
(actor = actors->GetNextActor(actorIt));)<br />
<br />
=== Changes in VTK between 3.2 and 4.0 ===<br />
<br />
* Changes to vtkDataSetAttributes, vtkFieldData and vtkDataArray: All attributes (scalars, vectors...) are now stored in the field data as vtkDataArray's. vtkDataSetAttributes became a sub-class of vtkFieldData. For backwards compatibility, the interface which allows setting/getting the attributes the old way (by passing in a sub-class of vtkAttributeData such as vtkScalars) is still supported but it will be removed in the future. Therefore, the developers should use the new interface which requires passing in a vtkDataArray to set an attribute. vtkAttributeData and it's sub-classes (vtkScalars, vtkVectors...) will be deprectated in the near future; developers should use vtkDataArray and it's sub-classes instead. We are in the process of removing the use of these classes from vtk filters.<br />
<br />
* Subclasses of vtkAttributeData (vtkScalars, vtkVectors, vtkNormals, vtkTCoords, vtkTensors) were removed. As of VTK 4.0, vtkDataArray and it's sub-classes should be used to represent attributes and fields. Detailed description of the changes and utilities for upgrading from 3.2 to 4.0 can be found in the package: http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
* Added special methods to data arrays to replace methods like<br />
<br />
tc SetTCoord i x y 0<br />
<br />
or<br />
<br />
vc SetVector i vx vy vz<br />
<br />
in interpreted languages (Tcl, Python, Java). Use:<br />
<br />
tc SetTuple2 i x y<br />
<br />
or<br />
<br />
vc SetTuple3 i vx vy vz<br />
<br />
* Improved support for parallel visualization: vtkMultiProcessController and it's sub-classes have been re-structured and mostly re-written. The functionality of vtkMultiProcessController have been re-distributed between vtkMultiProcessController and vtkCommunicator. vtkCommunicator is responsible of sending/receiving messages whereas vtkMultiProcessController (and it's subclasses) is responsible of program flow/control (for example processing rmi's). New classes have been added to the Parallel directory. These include vtkCommunicator, vtkMPIGroup, vtkMPICommunicator, vtkSharedMemoryCommunicator, vtkMPIEventLog... There is now a tcl interpreter which supports parallel scripts. It is called pvtk and can be build on Windows and Unix. Examples for both Tcl and C++ can be found in the examples directories.<br />
<br />
* vtkSocketCommunicator and vtkSocketController have been added. These support message passing via BSD sockets. Best used together with input-output ports.<br />
<br />
* Since it was causing very long compile times (it essentially includes every vtk header file) and it was hard to maintain (you had to add a line whenever you added a class to VTK) vtk.h was removed. You will have to identify the header files needed by your application and include them one by one.<br />
<br />
* vtkIterativeClosestPointTransform has been added. This class is an implementation of the ICP algorithm. It matches two surfaces using the iterative closest point (ICP) algorithm. The core of the algorithm is to match each vertex in one surface with the closest surface point on the other, then apply the transformation that modify one surface to best match the other (in a least square sense).<br />
<br />
* The SetFileName, SaveImageAsPPM and related methods in vtkRenderWindow have been removed. vtkWindowToImageFilter combined with any of the image writers provides greater functionality.<br />
<br />
* Support for reading and writing PGM and JPEG images has been included.<br />
<br />
* Methods with parameters of the form "type param[n]" are wrapped. Previously, these methods were only wrapped if the array was declared 'const'. The python wrappers will allow values to be returned in the array.<br />
<br />
* The directory structure was completely reorganized. There are now subdirectories for Common (core common classes) Filtering (superclasses for filtering operations) Imaging (filters and sources that produce images or structured points) Graphics (filters or sources that produce data types other than ImageData and StructuredPoints) IO (file IO classes that do not require Rendering support) Rendering (all actors mappers annotation and rendering classes) Hybrid (typically filters and sources that require support from Rendering or both Imaging and Graphics) Parallel (parallel visualization support classes) Patented (patented classes) Examples (documented examples) Wrapping (support for the language wrappers). In many directories you will see a Testing subdirectory. The Testing subdirectories contain tests used to validate VTKs operation. Some tests may be useful as examples but they are not well documented.<br />
<br />
* The Build process for VTK now uses CMake (found at www.cmake.org) This replaces pcmaker on windows and configure on UNIX. This resolves some longstanding problems and limitation we were having with pcmaker and configure, and unifies the build process into one place.<br />
<br />
=== Changes to VTK between 4.0 and 4.2 ===<br />
<br />
* Use of macros to support serialization, standardize the New method, and provide the Superclass typedef.<br />
<br />
* Subclassing of VTK classes in the python wrappers (virtual method hooks are not provided).<br />
<br />
* vtkImageWindow, vtkImager, vtkTkImageWindowWidget and their subclasses have been removed to reduce duplicated code and enable interation in ImageWindows. Now people should use vtkRenderer and vtkRenderWindow instead. vtkImageViewer still works as a turn key image viewing class although it now uses vtkRenderWindow and vtkRenderer internally instead of vtkImageWindow and vtkImager.<br />
<br />
* New class: vtkBandedPolyDataContourFilter. Creates solid colored bands (like you find on maps) of scalar value.<br />
<br />
* Event processing: Several new events to VTK were added (see vtkCommand.h). Also event processing can now be prioritized and aborted. This allows applications to manage who processes which events, and terminates the processing of a particular event if desired.<br />
<br />
* 3D Widgets: A new class vtkInteractorObserver was added to observe events on vtkRenderWindowInteractor. Using the new event processing infrastructure, multiple 3D widgets (subclasses of vtkInteractorObserver) can be used simultaneously to process interactions. Several new 3D widgets have been added including:<br />
** vtkLineWidget<br />
** vtkPlaneWidget<br />
** vtkImagePlaneWidget<br />
** vtkBoxWidget<br />
** vtkSphereWidget<br />
<br />
* Besides providing a representation, widgets also provide auxiliary functionality such as providing transforms, implicit functions, plane normals, sphere radius and center, etc.<br />
<br />
* New class: vtkInstantiator provides a means by which one can create an instance of a VTK class using only the name of the class as a string.<br />
<br />
* New class: vtkXMLParser provides a wrapper around the Expat XML parsing library. A new parser can be written by subclassing from vtkXMLParser and providing a few simple virtual method implementations.<br />
<br />
* TIFF reader is now implemented using libtiff, which makes it capable of reading almost all available TIFF formats. The libtiff is also available internally as vtktiff.<br />
<br />
* New method (all sub-classes of vtkObject): Added a virtual function called NewInstance to vtkTypeMacro. NewInstance creates and returns an object of the same type as the current one. It does not copy any properties. The returned pointer is of the same type as the pointer the method was invoked with. This method should replace all the MakeObject methods scattered through VTK.<br />
<br />
* vtkSetObject macro is depricated for use inside the VTK. It is still a valid construct in projects that use VTK. Instead use vtkCxxSetObjectMacro which does the same thing.<br />
<br />
* vtkPLOT3DReader have been improved. It now supports:<br />
** multigrid (each block is one output)<br />
** ascii<br />
** fortran-style byte counts<br />
** little/big endian<br />
** i-blanking (partial)<br />
<br />
* A new vtkTextProperty class has been created, and duplicated text API s have been obsoleted accordingly. Check the<br />
[[VTK_FAQ#Text_properties_in_VTK_4.2|Text properties in VTK 4.2]] FAQ entry for a full description of the change.<br />
<br />
=== How do I upgrade my existing C++ code from 3.2 to 4.x? ===<br />
<br />
This is (a corrected version of) an email that was posted to vtkusers.<br />
Please feel free to correct or add anything.<br />
<br />
{| cellspacing="3" <br />
|- valign="top"<br />
|width="55%" bgcolor="#f0f0ff" style="border:1px solid #ffc9c9;padding:1em;padding-top:0.5em;"|<br />
<br />
I've just ported my medium-sized (40K lines) application from vtk3.2 to<br />
vtk4.x. I thought I would share my experiences with you, in case there<br />
were people out there contemplating it but a bit scared.<br />
<br />
One source of information for upgrading code is:<br />
<br />
http://www.vtk.org/files/misc/Upgrading.zip<br />
<br />
I'm using VC++6 + MFC on Win2K and was unable/unwilling to run the<br />
script in the zip file.<br />
<br />
So,<br />
<br />
I switched all my include directories to the new VTK ones and<br />
recompiled. 337 errors, not unexpectedly. Most concerned vtkScalars and<br />
vtkTCoords which have both been removed. Where I was using single value<br />
scalars, like this:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetNumberOfScalars(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetScalar(i,2.3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *scalars = vtkFloatArray::New();<br />
scalars->SetNumberOfComponents(1);<br />
scalars->SetNumberOfTuples(N_POINTS);<br />
...<br />
polydata->GetPointData()->SetScalars(scalars);<br />
...<br />
scalars->SetTuple1(i,2.3);<br />
...<br />
<br />
OK so far, far fewer errors.<br />
<br />
Where I had 2D texture coordinates:<br />
<br />
vtkTCoords *tcoords = vtkTCoords::New();<br />
tcoords->SetNumberOfTCoords(N);<br />
...<br />
float p[3];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTCoord(i,p);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkFloatArray *tcoords = vtkFloatArray::New();<br />
tcoords->SetNumberOfComponents(2);<br />
tcoords->SetNumberOfTuples(N);<br />
...<br />
float p[2];<br />
p[0]=x; p[1]=y;<br />
tcoords->SetTuple(i,p);<br />
....<br />
<br />
All well and good, still fewer errors. Make sure you call<br />
SetNumberOfComponents *before* SetNumberOfTuples else you'll get<br />
problems (I did!).<br />
<br />
Where I was creating 0-255 image data and had been using:<br />
<br />
vtkScalars* scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
...<br />
<br />
Going well!<br />
<br />
When creating RGB images, I had been using:<br />
<br />
vtkScalars *scalars = vtkScalars::New();<br />
scalars->SetDataTypeToUnsignedChar();<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfScalars(X*Y);<br />
...<br />
scalars->SetActiveComponent(0);<br />
scalars->SetScalar(i,val1);<br />
scalars->SetActiveComponent(1);<br />
scalars->SetScalar(i,val2);<br />
scalars->SetActiveComponent(2);<br />
scalars->SetScalar(i,val3);<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkUnsignedCharArray *scalars = vtkUnsignedCharArray::New()<br />
scalars->SetNumberOfComponents(3);<br />
scalars->SetNumberOfTuples(X*Y);<br />
...<br />
scalars->SetComponent(i,0,val1);<br />
scalars->SetComponent(i,1,val2);<br />
scalars->SetComponent(i,2,val3);<br />
...<br />
<br />
My remaining errors concerned vtkWin32OffscreenRenderWindow that has<br />
been removed. Where I had been using:<br />
<br />
vtkWin32OffscreenRenderWindow *offscreen = vtkWin32OffscreenRenderWindow::New();<br />
...<br />
<br />
I replaced with:<br />
<br />
vtkWin32OpenGLRenderWindow *offscreen = vtkWin32OpenGLRenderWindow::New();<br />
offscreen->SetOffScreenRendering(1);<br />
...<br />
<br />
All done. I'd had to throw in some #include "vtkFloatArray.h" and things<br />
like that of course. Zero compile errors.<br />
<br />
Had to remember to link against the new vtk lib files, so I removed<br />
<br />
vtkdll.lib <br />
<br />
and added<br />
<br />
vtkCommon.lib<br />
vtkGraphics.lib<br />
<br />
etc.<br />
<br />
Zero link errors. My program is up and running again, no apparant<br />
problems. Plus now I can use all the new features of vtk4. (And I'm sure<br />
it's faster but maybe that's my imagination.)<br />
<br />
All this took me about three hours.<br />
<br />
Bye!<br />
<br />
Tim.<br />
|}<br />
<br />
=== What is the release schedule for VTK ===<br />
<br />
VTK has a formal release every eight to sixteen months. VTK 4.0 was cut in December 2001 and released in March 2002. VTK 4.2 was releaseed in February 2003. VTK 4.4 (which was an interim release) was released at the end of 2003. VTK 5.0 was released in January 2006, 5.0.1 in July 2006, 5.0.2 in September 2006, 5.0.3 in March 2007, and 5.0.4 in January 2008.<br />
<br />
=== Roadmap: What changes are being considered for VTK ===<br />
<br />
This is a list of changes that are being considered for inclusion into<br />
VTK. Some of these changes will happen while other changes we would like<br />
to see happen but may not due to funding or time issues. For each change<br />
we try to list what the change is, when we hope to complete it, if it is<br />
actively being developed. Detailed discussion on changes is limited to<br />
the vtk-developers mailing list.<br />
<br />
# Modify existing image filters to use the new vtkImageIterator etc. Most simple filters have been modified to use ithe iterator in VTK 4.2. It would be nice to have some sort of efficient neighborhood iterators but so far we haven't come up with any.<br />
# Rework the polydata and unstructured grid structures (vtkMesh ??). Related ideas include:<br />
#* Make UnstructuredGrid more compact by removing the cell point count from the vtkCellArray. This will reduce the storage required by each cell by 4 bytes.<br />
#* Make vtkPolyData an empty subclass of vtkUnstructuredGrid. There are a number of good reasons for this but it is a tricky task and backwards compatibility needs to be maintained.<br />
# More parallel support, including parallel compositing algorithms<br />
# Algorithms like LIC (http://www-courses.cs.uiuc.edu/~cs419/lic.pdf), maybe a couple terrain-decimation algorithms<br />
# Further integration of STL and other important C++ constructs (like templates)<br />
<br />
VTK 4.4 (intermediate release, end of 2003)<br />
<br />
* convert APIs to double (done)<br />
* remove old callbacks (done)<br />
* blanking<br />
* ref count observers (done)<br />
* switch collections to use iterators (done)<br />
* improve copyright (done)<br />
<br />
VTK 5.0 (major release, early 2005)<br />
<br />
* new pipeline mechanism (see [[Media:Pipeline.pdf|Pipeline.pdf]])<br />
* time support<br />
* true AMR support<br />
<br />
=== Changes to Interactors ===<br />
<br />
The Interactors have been updated to use the Command/Observer events of<br />
vtk. The vtkRenderWindowInteractor now has ivars for all the event<br />
information. There is a new class called<br />
vtkGenericRenderWindowInteractor that can be used to set up the bindings<br />
from other languages like python, Java or TCl.<br />
<br />
A new class vtkInteractorObserver was also added. It has a<br />
SetInteractor() method. It observes the keypress and delete events<br />
invoked by the render window interactor. The keypress activation value<br />
for a widget is now 'i' (although this can be programmed).<br />
vtkInteractorObserver has the state ivar Enabled. All subclasses must<br />
have the SetEnabled(int) method. Convenience methods like On(), Off(),<br />
EnabledOn(), and EnabledOff() are available. The state of the interactor<br />
observer is obtained using GetEnabled(). The SetEnabled(1) method adds<br />
observers to watch the interactor (appropriate to the particular<br />
interactor observer) ; SetEnabled(0) removes the observers . There are<br />
two new events: EnableEvent and DisableEvent which are invoked by the<br />
SetEnabled() method.<br />
<br />
The events also support the idea of priority now. When you add an<br />
observer, you can specify a priority from 0 to 1. Higher values will be<br />
called back first. An observer can also tell the object not to call any<br />
more observers. This way you can handle an event, and stop further<br />
processing. In this way you can add handlers to InteractorStyles without<br />
sub-classing and from wrapped languages.<br />
<br />
For more information see: vtkGenericRenderWindowInteractor,<br />
vtkRenderWindowInteractor, vtkInteractorObserver.<br />
<br />
=== Header files and vtkSetObjectMacro ===<br />
<br />
On some platforms such as MS Visual Studio .NET, compiler is not capable<br />
of handling too big input files. Some VTK files with all includes do<br />
become big enough to overwhelm the compiler. The solution is to minimize<br />
the amount of includes. This especially goes for header files, because<br />
they propagate to other files. Every class header file should include<br />
only the parent class header file. If there is no other alternative, you<br />
should put a comment next to include file explaining why the file has to<br />
be included.<br />
<br />
The related issue is with vtkSetObjectMacro. This file calles some<br />
methods on an argument class, which implies that the argument class<br />
header file has to be included. The result is bloat on the header files.<br />
The solution is to not use vtkSetObjectMacro but vtkCxxSetObjectMacro.<br />
The difference is that vtkCxxSetObjectMacro goes in the Cxx file and not<br />
in the header file.<br />
<br />
Example: Instead of<br />
<br />
#include "vtkBar.h"<br />
class vtkFoo : public vtkObject<br />
{ ...<br />
vtkSetObjectMacro(Bar, vtkBar);<br />
...<br />
};<br />
<br />
Do:<br />
<br />
class vtkBar;<br />
class vtkFoo : public vtkObject<br />
{<br />
...<br />
virtual void SetBar(vtkBar*);<br />
...<br />
};<br />
<br />
and add the following line to vtkFoo.cxx<br />
<br />
vtkCxxSetObjectMacro(vtkFoo,Bar,vtkBar);<br />
<br />
=== Text properties in VTK 4.2 ===<br />
<br />
A new<br />
[http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html vtkTextProperty]<br />
class has been added to VTK 4.2.<br />
<br />
This class factorizes text attributes that used to be spread out and<br />
duplicated in many different classes (mostly 2D actors and text<br />
mappers). Among those attributes, font family, font size,<br />
bold/italic/shadow properties, horizontal and vertical justification,<br />
line spacing and offset have been retained, whereas new attributes like<br />
color and opacity have been introduced.<br />
<br />
We tried to make sure that you can use a vtkTextProperty to modify text<br />
properties in the same way a vtkProperty can be used to modify the<br />
surface properties of a geometric object. In that regard, you should be<br />
able to share a vtkTextProperty between different actors or assign the<br />
same vtkTextProperty to an actor that offers multiple vtkTextProperty<br />
attributes ([http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlot]<br />
for example).<br />
<br />
Here is a quick example:<br />
<br />
vtkTextActor *actor0 = vtkTextActor::New();<br />
actor0->GetTextProperty()->SetItalic(1);<br />
//<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
//<br />
vtkTextActor *actor1 = vtkTextActor::New();<br />
actor1->SetTextProperty(tprop);<br />
//<br />
vtkTextActor *actor2 = vtkTextActor::New();<br />
actor2->SetTextProperty(tprop);<br />
<br />
*Backward compatibility issues*:<br />
<br />
1) Color and Opacity:<br />
<br />
The text color and text opacity settings are now controlled by the<br />
vtkTextProperty Color and Opacity attributes instead of the<br />
corresponding actor's color and opacity attributes. In the following<br />
example, those settings were controlled by the attributes of the<br />
vtkProperty2D attached to the vtkActor2D (vtkTextActor). The<br />
vtkTextProperty attributes should be used instead:<br />
<br />
vtkTextActor *actor = vtkActor::New();<br />
actor->GetProperty()->SetColor(...);<br />
actor->GetProperty()->SetOpacity(...);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetColor(...);<br />
actor->GetTextProperty()->SetOpacity(...);<br />
<br />
To make migration easier for a while, we have set the vtkTextProperty<br />
default color to ''(-1.0, -1.0, -1.0)'' and the default opacity to ''-1.0''.<br />
These "magic" values are checked by the underlying text mappers at<br />
rendering time. If they are found, the color and opacity of the 2D<br />
actor's vtkProperty2D are used, just as it was in VTK 4.1.<br />
<br />
2) API (i.e. SetBold(), SetItalic(), etc)<br />
<br />
Most of the VTK classes involving text used to provide their own text<br />
attributes like Bold, Italic, Shadow, FontFamily. Thus, each of those<br />
classes would duplicate the vtkTextMapper API through methods like<br />
SetItalic(), SetBold(), SetFontFamily(), etc.<br />
<br />
Moreover, if one class had different text elements (say, for example,<br />
the title and the labels of a scalar bar), there was no way to modify<br />
the text properties of these elements separately.<br />
<br />
The vtkTextProperty class has been created to address both issues, by<br />
obsoleting those duplicated attributes and methods and providing a<br />
unified way to access text properties, and by allowing each class to<br />
associate different vtkTextProperty to different text elements.<br />
<br />
Migrating your code basically involves using the old API on your actor's<br />
vtkTextProperty instead of the actor itself. For example:<br />
<br />
actor->SetBold(1);<br />
<br />
becomes:<br />
<br />
actor->GetTextProperty()->SetBold(1);<br />
<br />
When a class provides different vtkTextProperty for different text<br />
elements, the TextProperty attribute is usually prefixed with that<br />
element type. Example: AxisTitleTextProperty, or AxisLabelTextProperty.<br />
This allows you to set different aspect for each text elements. If you<br />
want to use the same properties, you can either set the same values on<br />
each vtkTextProperty, or make both vtkTextProperty point to the same<br />
vtkTextProperty object. Example:<br />
<br />
actor->GetAxisLabelTextProperty()->SetBold(1);<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
or:<br />
<br />
vtkTextProperty *tprop = vtkTextProperty::New();<br />
tprop->SetBold(1);<br />
actor->SetAxisLabelTextProperty(tprop);<br />
actor->SetAxisTitleTextProperty(tprop);<br />
<br />
or:<br />
<br />
actor->SetAxisLabelTextProperty(actor->GetAxisTitleTextProperty());<br />
actor->GetAxisTitleTextProperty()->SetBold(1);<br />
<br />
The following list specifies the name of the text properties used in the<br />
VTK classes involving text.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextMapper.html vtkTextMapper]:<br />
* you can still use the vtkTextMapper + vtkActor2D combination, but we would advise you to use a single vtkTextActor instead, this will give you maximum flexibility.<br />
* has 1 text prop: TextProperty, but although you have access to it, do not twwak it unless you are using vtkTextMapper with a vtkActor2D. In all other cases, use the text prop provided by the actor (see below).<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkTextActor.html vtkTextActor]:<br />
* has 1 text prop: TextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLabeledDataMapper.html vtkLabeledDataMapper]:<br />
* has 1 text prop: LabelTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCaptionActor2D.html vtkCaptionActor2D]:<br />
* has 1 text prop: CaptionTextProperty. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkLegendBoxActor.html vtkLegendBoxActor]:<br />
* has 1 text prop: EntryTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkAxisActor2D.html vtkAxisActor2D],<br />
[http://www.vtk.org/doc/nightly/html/classvtkParallelCoordinatesActor.html vtkParallelCoordinatesActor], and<br />
[http://www.vtk.org/doc/nightly/html/classvtkScalarBarActor.html vtkScalarBarActor]:<br />
* have 2 text props: TitleTextProperty, LabelTextProperty.<br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkXYPlotActor.html vtkXYPlotActor]:<br />
* has 3 text prop: TitleTextProperty (plot title), AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)<br />
* the legend box text prop (i.e. entry text prop) can be retrieved through actor->GetLegendBoxActor()->GetEntryTextProperty()<br />
* the X (or Y) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/YAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched. <br />
<br />
[http://www.vtk.org/doc/nightly/html/classvtkCubeAxesActor2D.html vtkCubeAxesActor2D]:<br />
* has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title and label of all axes)<br />
* the X (Y or Z) axis text props (i.e. title and label text props) can be retrieved through actor->GetX/Y/ZAxisActor2D->GetTitle/LabelTextProperty(), and will override the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as long as they remain untouched.<br />
<br />
=== Forward declaration in VTK 4.x ===<br />
<br />
Since VTK 4.x all classes have been carefully inspected to only include the necessesary headers, and do what is called 'forward declaration' for all other needed classes. Thus, when you compile your projects using a filter that takes as input a dataset and you are passing an imagedata: you need to explicitely include imagedata within your implementation file. This is true for all data types.<br />
<br />
For example, if you get this error:<br />
<br />
no matching function for call to `vtkContourFilter::SetInput(vtkImageData*)'<br />
VTK/Filtering/vtkDataSetToPolyDataFilter.h:44:<br />
candidates are: virtual void vtkDataSetToPolyDataFilter::SetInput(vtkDataSet*)<br />
<br />
This means you need to add in your code : #include "vtkImageData.h"<br />
<br />
=== Using Volume Rendering in VTK ===<br />
<br />
I recently updated my VTK CVS version. And my c++ code that use to work fine are now complaining about:<br />
<br />
undefined reference to `vtkUnstructuredGridAlgorithm::SetInput(vtkDataObject*)'<br />
undefined reference to `vtkUnstructuredGridAlgorithm::GetOutput()' <br />
<br />
There is now a new subfolder and a new option to enable building the VolumeRendering library. You have to turn VTK_USE_VOLUMERENDERING to ON in order to use it. Also make sure that your executable is linking properly to this new library:<br />
<br />
ADD_EXECUTABLE(foo foo.cxx)<br />
TARGET_LINK_LIBRARIES(foo vtkVolumeRendering)<br />
<br />
=== API Changes in VTK 5.2 ===<br />
<br />
==== <tt>vtkProp::RenderTranslucentGeometry()</tt> is gone ====<br />
<br />
<tt>vtkProp::RenderTranslucentGeometry()</tt> is gone and has been broken down into 3 methods:<br />
* <tt>HasTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderTranslucentPolygonalGeometry()</tt><br />
* <tt>RenderVolumetricGeometry()</tt><br />
<br />
Here is what to change in a vtkProp subclass:<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry only, override <tt>HasTranslucentPolygonalGeometry()</tt> and <tt>RenderTranslucentPolygonalGeometry()</tt>. <b>Just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderTranslucentPolygonalGeometry()</tt> is not enough!</b><br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent volumetric geometry only, override <tt>RenderVolumetricGeometry()</tt>. In this case, just renaming <tt>RenderTranslucentGeometry()</tt> as <tt>RenderVolumetricGeometry()</tt> is OK.<br />
* If <tt>RenderTranslucentGeometry()</tt> was used to render translucent polygonal geometry and translucent volumetric geometry, override all 3 methods.<br />
<br />
The reason of this change is that <tt>HasTranslucentPolygonalGeometry()</tt> is used to decide if an expensive initialization of the new rendering algorithm of translucent polygonal geometry (depth peeling) is necessary. <tt>RenderTranslucentPolygonalGeometry()</tt> is called multiple times during the rendering of the translucent polygonal geometry of the scene. <tt>RenderVolumetricGeometry()</tt> is called in an additional pass, after depth peeling. For this reason, <b><tt>RenderTranslucentGeometry()</tt> cannot just be marked as deprecated but had to be removed from the API</b>.<br />
<br />
<br />
<br />
==== <tt>vtkImagePlaneWidget</tt> has action names changed ====<br />
from:<br />
enum<br />
{<br />
CURSOR_ACTION = 0,<br />
SLICE_MOTION_ACTION = 1,<br />
WINDOW_LEVEL_ACTION = 2<br />
};<br />
to:<br />
enum<br />
{<br />
VTK_CURSOR_ACTION = 0,<br />
VTK_SLICE_MOTION_ACTION = 1,<br />
VTK_WINDOW_LEVEL_ACTION = 2<br />
};<br />
<br />
==== <tt>GetOutput()</tt> now returns <tt>vtkDataObject</tt> for some algorithms ====<br />
<br />
The following algorithms now work on <tt>vtkGraph</tt> as well as <tt>vtkDataSet</tt>, so no <tt>GetOutput()</tt> longer returns <tt>vtkDataSet</tt>. To obtain the dataset, use <tt>vtkDataSet::SafeDownCast(filter->GetOutput())</tt><br />
* <tt>vtkArrayCalculator</tt><br />
* <tt>vtkAssignAttribute</tt><br />
* <tt>vtkProgrammableFilter</tt><br />
<br />
=== API Changes in VTK 5.4 ===<br />
* empty right now.<br />
=== API Changes in VTK 5.5 ===<br />
<br />
* vtkStreamTracer<br />
Changed<br />
enum Units <br />
{ <br />
TIME_UNIT, <br />
LENGTH_UNIT, <br />
CELL_LENGTH_UNIT <br />
}<br />
to<br />
enum Units<br />
{ <br />
LENGTH_UNIT = 1, <br />
CELL_LENGTH_UNIT = 2 <br />
}<br />
<br />
<br />
Changed<br />
* OUT_OF_TIME = 4<br />
to<br />
* OUT_OF_LENGTH = 4<br />
in enum ''ReasonForTermination''<br />
<br />
<br />
Changed<br />
* LastUsedTimeStep<br />
to<br />
* LastUsedStepSize<br />
<br />
<br />
Changed<br />
* MaximumPropagation<br />
* MaximumIntegrationStep<br />
* MinimumIntegrationStep<br />
* InitialIntegrationStep <br />
from type ''IntervalInformation'' to type ''double''.<br />
<br />
<br />
Added a member variable to the class<br />
* int IntegrationStepUnit<br />
<br />
<br />
The following APIs were '''removed''' from the class:<br />
* void SetMaximumProgration(int unit, double max)<br />
* void SetMaximumProgrationUnit(int unit)<br />
* int GetMaximumPropagationUnit()<br />
* void SetMaximumPropagationUnitToTimeUnit()<br />
* void SetMaximumPropagationUnitToLengthUnit()<br />
* void SetMaximumPropagationUnitToCellLengthUnit()<br />
* void SetMinimumIntegrationStep(int unit, double step)<br />
* void SetMinimumIntegrationStepUnit(int unit)<br />
* int GetMinimumIntegrationStepUnit()<br />
* void SetMinimumIntegrationStepUnitToTimeUnit()<br />
* void SetMinimumIntegrationStepUnitToLengthUnit()<br />
* void SetMinimumIntegrationStepUnitToCellLengthUnit()<br />
* void SetMaximumIntegrationStep(int unit, double step)<br />
* void SetMaximumIntegrationStepUnit(int unit)<br />
* int GetMaximumIntegrationStepUnit()<br />
* void SetMaximumIntegrationStepUnitToTimeUnit()<br />
* void SetMaximumIntegrationStepUnitToLengthUnit()<br />
* void SetMaximumIntegrationStepUnitToCellLengthUnit()<br />
* void SetInitialIntegrationStep(int unit, double step)<br />
* void SetInitialIntegrationStepUnit(int unit)<br />
* int GetInitialIntegrationStepUnit()<br />
* void SetInitialIntegrationStepUnitToTimeUnit()<br />
* void SetInitialIntegrationStepUnitToLengthUnit()<br />
* void SetInitialIntegrationStepUnitToCellLengthUnit()<br />
* void SetIntervalInformation(int unit, double interval, IntervalInformation& currentValues)<br />
* void SetIntervalInformation(int unit,IntervalInformation& currentValues)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength, double speed)<br />
* static double ConvertToTime(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToCellLength(IntervalInformation& interval, double cellLength, double speed)<br />
* static double ConvertToUnit(IntervalInformation& interval, int unit, double cellLength, double speed)<br />
<br />
<br />
The following APIs were added to the class:<br />
* int GetIntegrationStepUnit()<br />
* void SetIntegrationStepUnit(int unit)<br />
* void ConvertIntervals(double& step, double& minStep, double& maxStep, int direction, double cellLength)<br />
* static double ConvertToLength(double interval, int unit, double cellLength)<br />
* static double ConvertToLength(IntervalInformation& interval, double cellLength)<br />
<br />
<br />
* vtkInterpolatedVelocityField<br />
Added a new member variable and two associated functions:<br />
* bool NormalizeVector<br />
* vtkSetMacro(NormalizeVector, bool)<br />
* vtkGetMacro(NormalizeVector, bool)<br />
<br />
== OpenGL requirements ==<br />
VTK requires at least OpenGL 1.1. VTK currently (v6.1) makes use of up to OpenGL 2.1 and a handful of extensions. Currently (v6.1) VTK makes use of the compatibility context and is not OpenGL 3.0 core compliant (http://www.opengl.org/wiki/Core_And_Compatibility_in_Contexts). If a given algorithm requires an OpenGL version or extension greater than what's available on a given system then either a fallback algorithm will be employed, as in the case of depth peeling, or an error will be reported indicating the required extension could not be found. One can display information about the system's OpenGL implementation as seen by VTK through the LoadOpenGL ctest. From a terminal in VTK build dir run "ctest -R LoadOpenGL --verbose". This will dump various driver information and list the extensions that VTK can use.<br />
<br />
=== Terminology ===<br />
* a software component using OpenGL (like VTK) <b>requires</b> some minimal version of OpenGL and some minimal set of OpenGL extensions at runtime. At compile time, it <b>requires</b> an OpenGL header file (<tt>gl.h</tt>) compatible with some minimal version of the OpenGL API.<br />
* an OpenGL implementation (software (like Mesa) or hardware (combination of a graphic card and its driver) ) <b>supports</b> some OpenGL versions and a set of extensions.<br />
<br />
=== How do I check which OpenGL versions or extensions are supported by my graphic card or OpenGL implementation? ===<br />
==== Linux/Unix ====<br />
Two ways:<br />
* General method<br />
<pre><br />
$ glxinfo<br />
</pre><br />
* vendor specific tool<br />
if you have an nVidia card and nvidia-settings installed on it, run it and go to the OpenGL/GLX Information item under the X Screen 0 item.<br />
<br />
==== Windows ====<br />
You can download and use GLview http://www.realtech-vr.com/glview<br />
<br />
==== Mac OS X ====<br />
With Xcode installed, Macintosh HD->Developer->Applications->Graphic Tools->OpenGL Driver Monitor.app->Monitors->Renderer Info-><name of the OpenGL driver>->OpenGL Extensions<br />
<br />
=== VTK 5.0 ===<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.0? ====<br />
The <tt>gl.h</tt> file provided by your compiler/system/SDK has to define at least the OpenGL 1.1 API.<br />
<br />
(Note: the functions and macros defined in higher OpenGL API versions or in other OpenGL extensions are provided by <tt>glext.h</tt>, <tt>glxext.h</tt> and <tt>wglext.h</tt>. Those 3 files are official files taken from http://opengl.org/registry/ and already part of the VTK source tree).<br />
<br />
==== What is the minimal OpenGL version required by VTK5.0 at runtime? ====<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>.<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
=== VTK 5.2 ===<br />
==== What is the minimal OpenGL version of the API required to compile VTK5.2? ====<br />
Same answer than for VTK 5.0.<br />
<br />
==== What is the minimal OpenGL version required by VTK5.2 at runtime? ====<br />
All the VTK classes using OpenGL require an OpenGL implementation (software or hardware) >=1.1 except for <tt>vtkVolumeTextureMapper3D</tt>, <tt>vtkHAVSVolumeMapper</tt>,<br />
<tt>vtkGLSLShaderProgram</tt>, depth peeling and some hardware offscreen rendering using framebuffer objects (FBO).<br />
<br />
If you want to use <tt>vtkVolumeTextureMapper3D</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* extension <tt>GL_EXT_texture3D</tt> or OpenGL>=1.2<br />
and<br />
* extension <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
and either:<br />
* extensions <tt>GL_ARB_fragment_program</tt> and <tt>GL_ARB_vertex_program</tt><br />
or:<br />
* extensions <tt>GL_NV_texture_shader2</tt> and <tt>GL_NV_register_combiners</tt> and <tt>GL_NV_register_combiners2</tt><br />
<br />
If you want to use <tt>vtkHAVSVolumeMapper</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_draw_buffers</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_program</tt><br />
* <tt>GL_ARB_vertex_program</tt><br />
* <tt>GL_EXT_framebuffer_object</tt><br />
* either <tt>GL_ARB_texture_float</tt> or <tt>GL_ATI_texture_float</tt><br />
<br />
The following extension or OpenGL version is used by <tt>vtkHAVSVolumeMapper</tt> if provided (at runtime), but it is optional:<br />
* <tt>GL_ARB_vertex_buffer_object</tt> or OpenGL>=1.5<br />
<br />
If you want to use <tt>vtkGLSLShaderProgram</tt>, the following extensions or OpenGL versions are required (at runtime):<br />
* OpenGL>=1.3<br />
* <tt>GL_ARB_shading_language_100</tt> or OpenGL>=2.0,<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0.<br />
<br />
Depth peeling ( see [[VTK/Depth_Peeling | VTK Depth Peeling]] for more information) requires (at runtime):<br />
* <tt>GL_ARB_depth_texture</tt> or OpenGL>=1.4<br />
* <tt>GL_ARB_shadow</tt> or OpenGL>=1.4<br />
* <tt>GL_EXT_shadow_funcs</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_vertex_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_fragment_shader</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_shader_objects</tt> or OpenGL>=2.0<br />
* <tt>GL_ARB_occlusion_query</tt> or OpenGL>=1.5<br />
* <tt>GL_ARB_multitexture</tt> or OpenGL>=1.3<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
* <tt>GL_SGIS_texture_edge_clamp</tt> or <tt>GL_EXT_texture_edge_clamp</tt> or OpenGL>=1.2<br />
<br />
Hardware-based offscreen rendering using framebuffer object (FBO) will be used as the default offscreen method if the following extensions or OpenGL version are available (at runtime):<br />
* <tt>GL_EXT_framebuffer_object</tt><br />
and either <br />
* <tt>GL_ARB_texture_non_power_of_two</tt> or OpenGL>=2.0<br />
or<br />
* <tt>GL_ARB_texture_rectangle</tt><br />
In addition, if the the framebuffer needs a stencil buffer, extension <tt>GL_EXT_packed_depth_stencil</tt> is required. Even if all those extensions are supported, the chosen FBO format might<br />
not be supported by the card; in this case, this method of offscreen rendering is not used.<br />
<br />
== Miscellaneous questions ==<br />
<br />
=== Can't you split up the data file? ===<br />
<br />
The data is now in one file that is about 15 Megabytes. This is smaller<br />
than the original data files VTK used and we hope that this size is not<br />
a problem for people anymore. If it is please let us know.<br />
<br />
=== Do you have any shared library tips? ===<br />
<br />
VTK version 4.0 and later supports both shared and static libraries on<br />
most all platforms. For development we typically use shared libraries<br />
since they are faster to link when making small changes. You can control<br />
how VTK builds by setting the BUILD_SHARED_LIBS option in CMake.<br />
<br />
== Legal issues ==<br />
<br />
=== Is VTK FDA-Approved ? ===<br />
<br />
Given the fact that VTK is a software toolkit, it cannot be the<br />
subject of FDA approval as a medical device. We have discussed<br />
this topic in several occasions and received advice from FDA<br />
representatives, that can be summarized as follow:<br />
<br />
<br />
VTK is to be considered as an off-the-shelf (OTS) product that<br />
is used for supporting a higher level medical application/product.<br />
The developer of such application/product will be responsible for<br />
performing the validation processes described in FDA published<br />
guidelines for the development of software-related medical devices.<br />
<br />
For mode details see the page [[FDA Guidelines for Software Development]]<br />
<br />
=== What are the legal issues? ===<br />
<br />
The Visualization Toolkit software is provided under the following<br />
copyright. We think it's pretty reasonable. We do restrict the<br />
distribution of modified code. This is primarily a revision control<br />
issue. We don't want a bunch of renegade vtks running around without us<br />
having some idea why the changes were made and giving us a chance to<br />
incorporate them into the general release.<br />
<br />
The text of the VTK copyright is available [http://www.vtk.org/copyright.php here].<br />
<br />
=== What is the deal with the patents ===<br />
<br />
As the copyright mentions there are some patents used in VTK. If you use<br />
any code in the Patented/ directory for commercial application you<br />
should contact the patent holder and obtain a license.<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by General Electric Company: vtkDecimate, vtkMarchingCubes,<br />
vtkMarchingSquares, vtkDividingCubes, vtkSliceCubes and vtkSweptSurface.<br />
The GE contact is:<br />
<br />
Carl B. Horton<br />
Sr. Counsel, Intellectual Property<br />
3000 N. Grandview Blvd., W-710<br />
Waukesha, WI 53188<br />
Phone: (262) 513-4022<br />
E-Mail: mailto:Carl.Horton@med.ge.com<br />
<br />
As of VTK4.0 the following classes are known to use algorithms patented<br />
by Kitware, Inc.: vtkGridSynchronizedTemplates3D,<br />
vtkKitwareContourFilter.h, vtkSynchronizedTemplates2D, and<br />
vtkSynchronizedTemplates3D. The Kitware contact is:<br />
<br />
Ken Martin<br />
Kitware<br />
28 Corporate Drive, Suite 204,<br />
Clifton Park, NY 12065<br />
Phone:1-518-371-3971<br />
E-Mail: mailto:kitware@kitware.com<br />
<br />
=== Can VTK be used as part of a project distributed under a GPL License ? ===<br />
<br />
==== Short Answer ====<br />
<br />
Yes, it is fine to take VTK code and to include it in a project that is distributed under a GPL license.<br />
<br />
==== Long Answer ====<br />
<br />
===== Terms =====<br />
<br />
Let's call project X the larger project that:<br />
<br />
# Will include source code from VTK (in part or as a whole)<br />
# Will be distributed under GPL license<br />
<br />
Note in particular that:<br />
<br />
# The copyright notices in VTK files must be kept.<br />
# If VTK files are modified by the developers of project X, that fact must be clearly indicated.<br />
# Only the modifications of VTK files made by the developers of project X will be covered by a GPL license. The original VTK code remains covered by the VTK license.<br />
# The collection of copyrighted works (project X in this case), that includes VTK (in part or as a whole) and their software will be covered by a GPL license.<br />
<br />
===== Details =====<br />
<br />
As the [http://www.vtk.org/copyright.php VTK license] is a variation of the [http://www.opensource.org/licenses/bsd-license.php Modified BSD license], to which only the following term has been added:<br />
<br />
Modified source versions must be plainly marked as such, <br />
and must not be misrepresented as being the original software.<br />
<br />
and that the Modified BSD license is itself compatible with the GPL <br />
<br />
http://www.gnu.org/philosophy/license-list.html (Modified BSD license)<br />
<br />
Then the VTK license is also compatible with the GPL license. Since the terms of the GPL license do not preclude the additional term of the VTK license from being followed.<br />
<br />
NOTE: The licenses are only '''one way compatible'''.<br />
<br />
* You can use VTK code inside a GPL licensed project.<br />
* You '''can not''' use GPL licensed code inside VTK.<br />
<br />
That is the reason why there are no GPL third party libraries in VTK. Having GPL third party libraries in VTK would prevent closed source projects from being built against VTK.<br />
<br />
== Common problems and their solutions ==<br />
* There are some problems may that arise while building VTK that have very straight forward solutions. [[VTK/BuildingProblems|Here]] they are.<br />
* There are some problems that arise frequently that have very straight forward solutions. [[VTK/CommonProblems|Here]] they are.<br />
<br />
{{VTK/Template/Footer}}</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=VTK/Building/Windows&diff=56026VTK/Building/Windows2014-04-03T18:30:04Z<p>Martink: Bringing a bit more up to date, removing dead links</p>
<hr />
<div>== Building VTK on Windows using Visual Studio (from a zip/tar file) ==<br />
<br />
Note: VTK uses the standard approach for building CMake based projects on Windows. If you are familiar with building projects on Windows using CMake then you can use your normal process. For information on other options such as msys, nmake, etc see the documentation associated with CMake.<br />
<br />
=== Step 1 - Download VTK===<br />
Download VTK release you want from: [http://vtk.org/files/release/] and unpack the archive (zip or tar.gz (Do NOT download the exe - this is not the VTK library.) ) into<br />
C:\MyProjects\VTK-src<br />
<br />
You will probably want the latest one (highest version number) unless you have a specific reason to use an older one.<br />
<br />
=== Step 2 - Download CMake ===<br />
[http://cmake.org/HTML/Download.html Download CMake]. Choose the windows installer (cmake-x.y.z-win32.exe) and install it. Letting the cmake installer add itself to your path will make it easier but is not required.<br />
<br />
=== Step 3 - Create a build folder ===<br />
<br />
Create a folder<br />
C:\MyProjects\VTK-bin<br />
<br />
This is where we will store the compiled binaries<br />
<br />
=== Step 4 - Run CMake ===<br />
<br />
Start CMake, provide the source codes and binaries paths to CMake. Then press the Configure button to let CMake read the CMakeLists.txt from the source path and configure the variables. In your case you should have:<br />
<br />
Where is the source code: C:\MyProjects\VTK-src<br />
Where to build the binaries: C:\MyProjects\VTK-bin<br />
<br />
CMake may prompt you for what generator to use. Select the version of Visual Studio that matches what you have installed on your machine. Once CMake finishes Configuring you will see a number of options that can be turned on or off. Adjust as desired, configure and then generate.<br />
<br />
=== Step 5 - Open the Visual Studio project===<br />
<br />
Start up visual studio and then open the VTK.sln in C:\MyProjects\VTK-bin and build it. <br />
<br />
=== Step 6 - Install the project ===<br />
<br />
Installation, the VTK dll will be in<br />
C:\MyProjects\VTK-bin\bin\release<br />
therefore by default the system cannot find them. You have the choice in either copying the dll to<br />
c:\windows\system32<br />
or change the environment variable PATH to include the path:<br />
C:\MyProjects\VTK-bin\bin\release<br />
<br />
'''Be very careful if you have multiple VTK installed on your system that you are using the right one'''. It is strongly suggested that only one version of the VTK dll be on one system.<br />
<br />
=== Step 7 - Manual building ===<br />
<br />
When building your project if you don't use CMake, make sure that ''Additional Include Directories'' and ''Additional Library Directories'' (from within the Visual Studio interface) are pointing to the proper path of VTK-src<br />
<br />
== Installing VTK ==<br />
<br />
'''NOTE''':<br />
* It is assumed that you have already built VTK. If not refer to previous section on how to build VTK.<br />
<br />
Steps:<br />
# Start CMake (CMakeSetup.exe).<br />
# Configure VTK (select the correct binary directory in "Where to build the binaries").<br />
# Select the proper path for "CMAKE_INSTALL_PREFIX". It should be something like : "C:/MY INSTALLATION/VTK"<br />
# Click Configure<br />
# Click "OK"<br />
# Open Visual Studio, select the VTK.sln project from the binary directoy.<br />
# Make sure that ALL_BUILD is the selected target. Build it. It should be a noop.<br />
# Once this is done, select the "INSTALL" target. And build this target (eg. Right click on it, then Build this taget only). This will copy and the the correct permission for all the files needed to use VTK in the directory you have specified.<br />
<br />
<br />
[[Image:VSSolutionExplorer.png|Visual Studio Solution Explorer]]<br />
<br />
[[Image:INSTALLTarget.png|INSTALL Target]]</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=VTK/Building/Windows&diff=56025VTK/Building/Windows2014-04-03T16:24:11Z<p>Martink: </p>
<hr />
<div>== Building VTK on Windows using Visual Studio (from a zip/tar file) ==<br />
<br />
Note: VTK uses the standard approach for building CMake based projects on Windows. If you are familiar with building projects on Windows using CMake then you can use your normal process. For information on other options such as msys, nmake, etc see the documentation associated with CMake.<br />
<br />
=== Step 1 - Download VTK===<br />
Download VTK release you want from: [http://vtk.org/files/release/] and unpack the archive (zip or tar.gz (Do NOT download the exe - this is not the VTK library.) ) into<br />
C:\MyProjects\VTK-src<br />
<br />
You will probably want the latest one (highest version number) unless you have a specific reason to use an older one.<br />
<br />
=== Step 2 - Download CMake ===<br />
[http://cmake.org/HTML/Download.html Download CMake]. Choose the windows installer (cmake-x.y.z-win32.exe) and install it. Letting the cmake installer add itself to your patch will make it easier but is not required.<br />
<br />
=== Step 3 - Create a build folder ===<br />
<br />
Create a folder<br />
C:\MyProjects\VTK-bin<br />
<br />
This is where we will store the compiled binaries<br />
<br />
=== Step 4 - Run CMake ===<br />
<br />
Start CMake, provide the source codes and binaries paths to CMake. Then press Configure button to let CMake read the CMakeLists.txt from the source path and configure the variables. In your case you should have:<br />
<br />
Where is the source code: C:\MyProjects\VTK-src<br />
Where to build the binaries: C:\MyProjects\VTK-bin<br />
<br />
Once you hit 'Configure', make sure to turn on:<br />
* BUILD_SHARED_LIBS<br />
this causes the VTK dlls to be built.<br />
<br />
=== Step 5 - Open the Visual Studio project===<br />
<br />
Start up visual studio and then open the VTK.sln in C:\MyProjects\VTK-bin and build it. <br />
<br />
=== Step 6 - Install the project ===<br />
<br />
Installation, the VTK dll will be in<br />
C:\MyProjects\VTK-bin\bin\release<br />
therefore by default the system cannot find them. You have the choice in either copying the dll to<br />
c:\windows\system32<br />
or change the environment variable PATH to include the path:<br />
C:\MyProjects\VTK-bin\bin\release<br />
<br />
'''Be very careful if you have multiple VTK installed on your system that you are using the right one'''. It is strongly suggested that only one version of the VTK dll be on one system.<br />
<br />
=== Step 7 - Manual building===<br />
<br />
When building your project if you don't use CMake, make sure that ''Additional Include Directories'' and ''Additional Library Directories'' (from within the Visual Studio interface) are pointing to the proper path of VTK-src<br />
<br />
== Installing VTK ==<br />
<br />
'''NOTE''':<br />
* It is assumed that you have already built VTK. If not refer to previous section on how to build VTK.<br />
<br />
Steps:<br />
# Start CMake (CMakeSetup.exe).<br />
# Configure VTK (select the correct binary directory in "Where to build the binaries").<br />
# Select the proper path for "CMAKE_INSTALL_PREFIX". It should be something like : "C:/MY INSTALLATION/VTK"<br />
# Click Configure<br />
# Click "OK"<br />
# Open Visual Studio, select the VTK.sln project from the binary directoy.<br />
# Make sure that ALL_BUILD is the selected target. Build it. It should be a noop.<br />
# Once this is done, select the "INSTALL" target. And build this target (eg. Right click on it, then Build this taget only). This will copy and the the correct permission for all the files needed to use VTK in the directory you have specified.<br />
<br />
<br />
[[Image:VSSolutionExplorer.png|Visual Studio Solution Explorer]]<br />
<br />
[[Image:INSTALLTarget.png|INSTALL Target]]<br />
<br />
== Links ==<br />
* [http://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=502 Installing VTK 4.1.x on a windows PC]<br />
* [http://www.spinet.pl/~wilku/vtk-howto/ How to build VTK with Java support on Windows]<br />
* [http://www.duke.edu/~iwd/howto/VTK-Linux-Java_HOWTO.html Building VTK on Linux with Java support]</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake_Policies_Design_Discussion&diff=11817CMake Policies Design Discussion2008-03-13T16:00:32Z<p>Martink: </p>
<hr />
<div>This page describes a proposal for a formal backwards/forwards compatibility feature.<br />
<br />
=Motivating Examples=<br />
<br />
==The ADD_DEFINITIONS Command==<br />
<br />
Consider code such as<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
which tries to add the option<br />
<br />
-DFOO=\"hello\ world\"<br />
<br />
to the compile command line. The code works in CMake 2.4's <code>Unix Makefiles</code> generator and produces a definition as if<br />
<br />
#define FOO "hello world"<br />
<br />
appeared in the source code. It works only because of the way the makefile generator happens to place the definition string in the command line. It may not work with the VS IDE generators.<br />
In CMake HEAD we provide the <code>COMPILE_DEFINITIONS</code> directory property so that one may write<br />
<br />
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "FOO=\"hello world\"")<br />
<br />
to get the correct behavior on all generators. Since CMake HEAD contains the appropriate escaping support it is desirable to allow the user to write<br />
<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
and get the expected behavior. Unfortunately if we were to start escaping the definitions given to <code>add_definitions</code> we would break compatibility with projects that are already adding their own escapes. In hindsight we should have either supported escapes from the beginning or make the command give an error that the definition value is not supported, but it is too late now.<br />
A similar problem appears in the <code>add_custom_command</code> command where support for properly escaping all arguments was added late. The solution currently used by that command is to require the user to add a <code>VERBATIM</code> argument to the command to get proper escaping. Using that solution for <code>add_definitions</code> would make the user write<br />
<br />
add_definitions(VERBATIM "-DFOO=\"hello world\"")<br />
<br />
just to get CMake to do the right thing. For compatibility CMake would have to implement the wrong behavior by default forever.<br />
<br />
==Missing Link Directories==<br />
<br />
Projects used to be able to write this (wrong) code and it would work by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect <br />
because it asks CMake to link to <code>B</code> but does not provide the proper <br />
linker search path for it. It used to work by accident because the <br />
<code>-L/path/to</code> would get added as part of the implementation of linking to <br />
A. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
Currently we provide the <code>CMAKE_OLD_LINK_PATHS</code> variable to allow projects or users to quickly work around the problem. Full compatibility would require us to support thie behavior by default forever. That would allow new projects to be written with the same bug.<br />
<br />
An alternative is to require all libraries to be linked via full path (where target names are expanded automatically). Whenever a non-full-path is given we could produce a warning that tells the user to start using <code>find_library</code> or something like that but then implement the old linker search path computation for compatibility. It is desirable to let projects that have been updated for newer CMake versions tell CMake that they know what they are doing and to not warn or use the compatibility behavior.<br />
<br />
=Proposed Solution=<br />
<br />
We propose the following solution to this problem.<br />
<br />
Each change that introduces a compatibility issue is assigned a new identification number (like CMP0001). Then we try to detect cases in user code where it '''might''' be an issue and deal with it. We can maintain in the implementation of CMake a mapping from policy id to a rule to deal with the issue when encountered. The possible means of dealing with such cases are:<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Rule !! Behavior !! Meaning !! Default?<br />
|-<br />
| OLD || old || Project suppresses the diagnostic || never<br />
|-<br />
| NEW || new || Project declares the case has been resolved || never<br />
|-<br />
| WARN || old || Emit warning when case is encountered || most cases<br />
|-<br />
| REQUIRED_IF_USED || new || Must use the new behavior || future CMake release, compatibility can be dropped but still checked for<br />
|-<br />
| REQUIRED_ALWAYS || new || Must use the new behavior || future CMake release, compatibility is dropped as well as the code to check if the file uses this issue<br />
|}<br />
<br />
Several releases after a compatibility issue has been introduced we can remove implementation of support for the old behavior and set it to "REQUIRED" internally that requires a project to declare the issue NEW or to be of a CMake version such that we know it would have generated warning. See the feature lifespan example.<br />
<br />
==Proposed CMAKE_POLICY Command==<br />
<br />
We will introduce a new command for projects to use for setting the rule for each policy.<br />
<br />
The signature<br />
<br />
cmake_policy(<OLD|NEW> [policy-id1 [policy-id2 [...]]])<br />
<br />
sets a list of policies to use OLD or NEW behavior. It is an error to specify a policy id that does not exist (because it might refer to a policy id introduced in a future version of CMake).<br />
<br />
The signature<br />
<br />
cmake_policy(VERSION <major[.minor[.patch]]>)<br />
<br />
sets all rules for policies introduced in the specified version or below to NEW and all other rules to WARN. It also requires the version of CMake running to be at least that high.<br />
The <code>cmake_minimum_required(VERSION)</code> command can do something similar (but use of new commands versus fixing other issues are distinct cases so the defaults may need to be different).<br />
<br />
The signature<br />
<br />
cmake_policy(<PUSH|POP>)<br />
<br />
pushes or pops the current policy state on a stack. The stack is automatically pushed/popped when entering a new directory (under <code>add_subdirectory</code> for example). Within a directory the number of PUSH and POP calls must match or it is an error. This signature is useful in a .cmake script meant for inclusion in other projects. It could write<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(NEW CMP0001)<br />
... code using CMP0001 ...<br />
cmake_policy(POP)<br />
<br />
The command could also provide an alias for each policy id that is more human readable:<br />
<br />
cmake_policy(NEW CMP_ESCAPE_DEFINITIONS)<br />
<br />
==Examples==<br />
<br />
Let's define a few example policy ids<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Id !! Alias !! Description<br />
|-<br />
| CMP0000 || CMP_POLICY_SPECIFICATION || Projects should specify a cmake_policy command at their top level.<br />
|-<br />
| CMP0001 || CMP_ESCAPE_DEFINITIONS || Enable proper escaping of definitions added with ADD_DEFINITIONS<br />
|-<br />
| CMP0002 || CMP_ESCAPE_CUSTOM_COMMANDS || Enable proper escaping of custom command lines with ADD_CUSTOM_COMMAND, make VERBATIM argument an error<br />
|-<br />
| CMP0003 || CMP_NO_AUTOMATIC_LINK_PATHS || Disable generation of compatibility -L options on link lines<br />
|}<br />
<br />
The code<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
can now produce a warning CMP0001 that CMake does not know whether to escape the definition (only when a non-trivial value is given).<br />
<br />
The project may suppress the warning in their release branch:<br />
<br />
project(FOO)<br />
cmake_policy(OLD CMP_ESCAPE_DEFINITIONS)<br />
...<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
or fix the code:<br />
<br />
project(FOO)<br />
cmake_policy(NEW CMP_ESCAPE_DEFINITIONS)<br />
...<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
Either way CMake knows exactly how to handle the code and does not need to warn.<br />
<br />
Similarly, the code<br />
<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
may now produce a warning CMP0002 that CMake does not know whether to escape the command.<br />
The project may write<br />
<br />
project(FOO)<br />
cmake_policy(NEW CMP_ESCAPE_CUSTOM_COMMANDS)<br />
...<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
to get rid of the warning and use proper escaping.<br />
<br />
The code<br />
<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
may now produce a warning CMP0003 that library B may not have the correct link directory specified but then generate -L/path/to anyway. The project may write<br />
<br />
project(FOO)<br />
cmake_policy(NEW CMP_NO_AUTOMATIC_LINK_PATHS)<br />
...<br />
link_directories(/path/to)<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
Once the project has fixed all issues related to upgrading to CMake 2.6 it can just write<br />
<br />
project(FOO)<br />
cmake_policy(VERSION 2.6)<br />
<br />
to get all the updated behavior. Future versions of CMake (> 2.6) may then warn on their new policies.<br />
<br />
==Feature Lifespan Example==<br />
<br />
Using the CMP0001 || CMP_ESCAPE_DEFINITIONS example above let's examine how it would work. In CMake 2.4 definitions had to be escaped by the user which probably does not work on MSVC etc. So in 2.6 we want to start switching over to having CMake handle the escaping. <br />
<br />
* CMake 2.4: old behavior, issue CMP0001 does not even exist<br />
<br />
* CMake 2.6: issue CMP0001 is created and set to WARN and version number 2.6. By default old projects will still work but will receive a warning if they use this feature. The policy can be either made OLD <code>cmake_policy(OLD CMP0001)</code> with no other changes to the CMakeLists file or the issue can be fixed by changing their code and setting it to NEW <code>cmake_policy(NEW CMP0001)</code>. Or they can ignore it and just live with the warnings.<br />
<br />
* CMake 2.8: Nothing changes, stays as a warning<br />
<br />
* CMake 2.10: We change the default value of issue CMP_0001 to REQUIRED_IF_USED. Implementation of the old behavior is removed, but the check for its need is still present. If the user code causes CMake to hit the check then it must also have specified <code>cmake_policy(NEW CMP0001)</code> or <code>cmake_policy(VERSION 2.6)</code> (or higher). Otherwise an error is produced.<br />
<br />
* CMake 2.12: We change the default value of issue CMP0001 to REQUIRED_ALWAYS. Implementation of the old behavior '''and''' the check for it are removed. The user code '''must''' specify <code>cmake_policy(NEW CMP0001)</code> or <code>cmake_policy(VERSION 2.6)</code> (or higher) whether or not the feature is used. Otherwise an error is produced.<br />
<br />
==Discussion==<br />
<br />
This solution has the following advantages:<br />
<br />
* All compatibility issues are documented and given unique identifiers<br />
** Documentation can include association with CMake version ranges (when introduced, when REQUIRED, etc.)<br />
* We can be more aggressive about detecting cases without worrying about false positives because it is just a warning<br />
* When generating a warning or error message we can reference the feature id and tell the user what to do<br />
* Projects can be converted to newer CMake features incrementally<br />
* Project authors will be motivated by the warnings to update their code, but it will build for users without extra work<br />
* Code written that does not hit one of these issues will work without any special declarations<br />
** The hello-world example does not need to show version specification<br />
* We have an exit-path to remove support for a compatibility feature eventually<br />
** Make projects set the rule to NEW explicitly or via VERSION specification<br />
* Any compatibility bug introduced accidentally and reported by a user can be fixed in CMake by converting it to one of these issues<br />
<br />
Note <code>CMP0000</code> in the above example. This should be the first (lowest numbered) policy we introduce. We want all projects to specify a policy version level at the top:<br />
<br />
project(FOO)<br />
cmake_policy(VERSION 2.6)<br />
<br />
This should somehow interface with <code>cmake_minimum_required</code> since many projects have it already:<br />
<br />
project(FOO)<br />
cmake_minimum_required(VERSION 2.4)<br />
<br />
We could also consider making it an optional argument to the project command for brevity:<br />
<br />
project(FOO CMAKE 2.6)<br />
<br />
It should be a warning to encounter a command other than <code>project</code>, <code>cmake_policy</code> or <code>cmake_minimum_required</code> before a policy version has been set.<br />
<br />
==Interaction with Previous Compatibility Features==<br />
<br />
CMake 2.4 currently presents all users with the cache entry <code>CMAKE_BACKWARDS_COMPATIBILITY</code>. The policy mechanism replaces it, but we may still need to present it for old projects and honor it for cases supported by 2.4 in case projects set it. I propose the following behavior<br />
<br />
* CMake 2.6 does not present <code>CMAKE_BACKWARDS_COMPATIBILITY</code> by default<br />
* If the project does not set the policy version (which produces the CMP0000 warning) or sets the policy version to 2.4 or lower then we add <code>CMAKE_BACKWARDS_COMPATIBILITY</code> to the cache with a starting value of the policy version level.<br />
* It is an error for anything (project or user) to set <code>CMAKE_BACKWARDS_COMPATIBILITY</code> to a value of higher than 2.4.<br />
* Any check of the value performed by CMake 2.4 (for values 2.2 and lower of course) is left in place.<br />
* All other checks (for value 2.4) we have in CMake HEAD right now get converted to policies.<br />
<br />
<br />
There are a few other variables/properties checked by CMake HEAD that approximate the policy feature.<br />
<br />
* The variable <code>CMAKE_OLD_LINK_PATHS</code> is used for CMP0003 above.<br />
* The global property <code>ALLOW_DUPLICATE_CUSTOM_TARGETS</code> is used to allow multiple <code>ADD_CUSTOM_TARGET</code> commands to specify the same target.<br />
<br />
These (and others?) need to be converted to policies appropriately.<br />
<br />
<br />
CMake 2.4 provides the <code>VERBATIM</code> option to <code>ADD_CUSTOM_COMMAND</code> to enable correct escaping. This needs to be converted to a policy as follows<br />
<br />
* Old behavior is to accept VERBATIM or not and escape accordingly<br />
* New behavior is to escape correctly and reject the VERBATIM option</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake/Policies&diff=11816CMake/Policies2008-03-13T15:53:28Z<p>Martink: </p>
<hr />
<div>The CMake Policy mechanism provides backwards compatibility as a<br />
first-class feature.<br />
<br />
This page provides information intended for use by project developers to help update their projects to deal with new policies.<br />
<br />
=Motivation=<br />
<br />
CMake is an evolving project. The developers strive to support<br />
existing projects as much as possible as changes are made.<br />
Unfortunately there are some cases where it is not possible to fix<br />
bugs and preserve backwards compatibility at the same time. We give<br />
some examples here.<br />
<br />
==Fixing an Interface Breaks Work-Arounds==<br />
<br />
Consider the <code>add_definitions</code> command:<br />
<br />
add_definitions(-DFOO)<br />
<br />
When originally introduced the command was intended only to add simple<br />
definitions. Its implementation was simply to pass its arguments on<br />
to the compiler's command line. Since CMake supports configured<br />
header files using the <code>configure_file</code> command it is not<br />
necessary to pass complicated definitions on compile command lines.<br />
However, some project authors tried to do so anyway with code like<br />
<br />
add_definitions("-DFOO=\"some string\"")<br />
<br />
but found that it did not work. The string<br />
<br />
-DFOO="some string"<br />
<br />
would appear on the command line and the compiler would receive a<br />
definition equivalent to<br />
<br />
#define FOO some string<br />
<br />
Some authors proceeded to work around the problem by adding escape<br />
sequences manually:<br />
<br />
add_definitions("-DFOO=\"\\\"some string\\\"\"")<br />
<br />
The escape sequences work for some native build tools (such as Unix<br />
Makefiles) but not others. The proper way to deal with this issue was<br />
to fix the implementation in CMake to actually produce the correct<br />
escape sequences for each native build tool automatically.<br />
<br />
Unfortunately introducing the fix would break existing projects that<br />
add their own escape sequences because the escapes themselves would be<br />
escaped. In order to support such projects no fix was introduced for<br />
years. This allowed many more projects to continue to suffer from the<br />
problem and add their own work-arounds which must now also be<br />
supported.<br />
<br />
This problem with <code>add_definitions</code> is an example of a<br />
class of problems: how are we to fix an interface without breaking<br />
work-arounds for the very problem being fixed? The policy mechanism<br />
is a solution to this problem.<br />
<br />
==Changing an Implementation Breaks Projects Building Accidentally==<br />
<br />
When using CMake 2.4 or below projects may write this (wrong) code and it works by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect because it asks CMake to link to <code>B</code> but does not provide the proper linker search path for it. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
CMake 2.4 implemented the link to library A partly by adding<br />
<code>-L/path/to</code> to the linker command line. This allowed<br />
library B to be found even though no linker search path was provided<br />
for it. CMake 2.6 implements linking to library A by passing<br />
<code>/path/to/libA.so</code> directly to the linker as a path. This<br />
leaves out the <code>-L/path/to</code> which may prevent library B<br />
from being found.<br />
<br />
While the code above leading to this problem is technically wrong it<br />
worked with a previous CMake release and needs to be supported.<br />
Therefore CMake 2.6 has support for passing the directories containing<br />
libraries whose full paths are known as linker search paths even<br />
though they are not needed for correct user code. Full compatibility<br />
would require us to support this behavior by default forever. That<br />
would allow new projects to be written with the same bug.<br />
<br />
This problem is an example of a class of problems: how are we to fix<br />
an implementation without breaking projects depending on undocumented<br />
details of the original implementation? The policy mechanism is a<br />
solution to this problem.<br />
<br />
=Design Goals=<br />
<br />
The design goals for the CMake Policy mechanism were as follows:<br />
<br />
# '''Existing projects should build with versions of CMake newer than that used by the project authors'''<br />
#* Users should not need to edit code to get the projects to build<br />
#* Warnings may be issued but the projects should build<br />
# '''Correctness of new interfaces or bugs fixed in old ones should not be inhibited by compatibility requirements'''<br />
#* Any reduction in correctness of the latest interface is not fair to new projects<br />
# '''Every change to CMake that may require changes to project code should be documented'''<br />
#* Each change should also have a unique identifier that can be referenced by warning and error messages<br />
#* The new behavior is enabled only when the project has somehow indicated it is supported<br />
# '''We must be able to eventually remove code implementing compatibility with ancient CMake versions'''<br />
#* Such removal is necessary to keep the code clean and allow internal refactoring<br />
#* After such removal attempts to build projects written for ancient versions must fail with an informative message<br />
<br />
=Solution=<br />
<br />
We've introduced the notion of a '''policy''' for dealing with changes<br />
in CMake behavior. Each policy has<br />
<br />
* A name of the form '''<code>CMP''NNNN''</code>''' where ''NNNN'' is an integer identifier<br />
* '''OLD''' behavior that preserves compatibility with earlier versions of CMake<br />
* '''NEW''' behavior that is considered correct and preferred for use by new projects<br />
* Documentation detailing the motivation for the change and the OLD and NEW behaviors<br />
<br />
Projects may configure the setting of each policy to request OLD or<br />
NEW behavior. When CMake encounters user code that may be affected by<br />
a particular policy it checks to see whether the project has set the<br />
policy. If the policy has been set (to OLD or NEW) then CMake follows<br />
the behavior specified. If the policy has not been set then the old<br />
behavior is used but a warning is produced telling the project author<br />
to set the policy.<br />
<br />
==Setting Policies by CMake Version==<br />
<br />
In most cases a project release should simply set a ''policy version'' corresponding to the release version of<br />
CMake for which the project is written. Setting the policy version<br />
requests NEW behavior for all policies introduced in the corresponding<br />
version of CMake or earlier. Policies introduced in later versions<br />
are marked as not set in order to produce proper warning messages.<br />
<br />
The policy version is set using the <code>cmake_policy</code><br />
command's <code>VERSION</code> signature. For example, the code<br />
<br />
cmake_policy(VERSION 2.6)<br />
<br />
will request NEW behavior for all policies introduced in CMake 2.6 or<br />
earlier. The <code>cmake_minimum_required</code> command will also<br />
set the policy version which is convenient for use at the top of<br />
projects. A project should typically begin with the lines<br />
<br />
cmake_minimum_required(VERSION 2.6)<br />
project(MyProject)<br />
# ...code using CMake 2.6 policies<br />
<br />
Of course one should replace "<code>2.6</code>" with a higher version<br />
as necessary.<br />
<br />
When a new version of CMake is released that introduces new policies<br />
it will still build old projects because they do not request NEW<br />
behavior for any of the new policies. When starting a new project one<br />
should always specify the most recent release of CMake to be supported<br />
as the policy version level. This will make sure that the project is<br />
written to work using policies from that version of CMake and not<br />
using any old behavior.<br />
<br />
Policy CMP0000 has been introduced to require all projects to specify a policy version in their top-level CMakeLists.txt file. If no policy version is set CMake will warn and assume a policy version of 2.4. This allows existing projects that do not specify <code>cmake_minimum_required</code> to build as they would have with CMake 2.4.<br />
<br />
==Setting Policies Individually==<br />
<br />
Each policy may be set individually to help project authors<br />
incrementally convert their projects to use new behavior or silence<br />
warnings about dependence on old behavior. The<br />
<code>cmake_policy</code> command's <code>SET</code> signature may be<br />
used to explicitly request OLD or NEW behavior for a particular<br />
policy.<br />
<br />
For example, CMake 2.6 introduces policy <code>CMP0002</code> which<br />
requires all logical target names to be globally unique (duplicate<br />
target names previously worked in some cases by accident but were not<br />
diagnosed). Projects using duplicate target names and working<br />
accidentally will receive warnings referencing the policy. The<br />
warnings may be silenced by the code<br />
<br />
cmake_policy(SET CMP0002 OLD)<br />
<br />
which explicitly tells CMake to use OLD behavior for the policy<br />
(silently accept duplicate target names). Another option is to use<br />
the code<br />
<br />
cmake_policy(SET CMP0002 NEW)<br />
<br />
to explicitly tell CMake to use NEW behavior (produce an error when a<br />
duplicate target is created). Once this is added to the project it<br />
will not build until the author removes the duplicate targets.<br />
<br />
==Policy Stack==<br />
<br />
Policy settings are scoped using a stack. A new level of the stack is<br />
pushed when entering a new subdirectory of the project (with<br />
<code>add_subdirectory</code>) and popped when leaving it. Therefore<br />
setting a policy in one directory of a project will not affect parent<br />
or sibling directories but will affect subdirectories.<br />
<br />
This is useful when a project contains subprojects maintained<br />
separately but built inside the tree. The top-level<br />
<code>CMakeLists.txt</code> file in a project may write<br />
<br />
cmake_policy(VERSION 2.6)<br />
project(MyProject)<br />
add_subdirectory(OtherProject)<br />
# ... code requiring new behavior as of CMake 2.6 ...<br />
<br />
while the <code>OtherProject/CMakeLists.txt</code> file contains<br />
<br />
cmake_policy(VERSION 2.4)<br />
project(OtherProject)<br />
# ... code that buidls with CMake 2.4 ...<br />
<br />
This allows the main project to be updated to CMake 2.6 while the<br />
subproject continues to build with CMake 2.4 until its maintainers<br />
update it.<br />
<br />
User code may use the <code>cmake_policy</code> command to PUSH and<br />
POP its own stack levels as long as every PUSH must be paired with a<br />
POP. This is useful to temporarily request different behavior for a<br />
small section of code. For example, policy <code>CMP0003</code><br />
removes extra link directories that used to be included when NEW<br />
behavior is used. While incrementally updating a project it may be<br />
difficult to build a particular target with the NEW behavior but all<br />
other targets are okay. The code<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP0003 OLD) # use old-style link directories for now<br />
add_executable(myexe ...)<br />
cmake_policy(POP)<br />
<br />
will silence the warning and use the OLD behavior for that target.<br />
<br />
==Interaction with Previous Compatibility Mechanisms==<br />
<br />
CMake 2.4 and below dealt with backwards compatibility by providing<br />
the <code>CMAKE_BACKWARDS_COMPATIBILITY</code> variable as a cache<br />
entry. The variable could be set by the user when building a project<br />
to tell CMake to try to support an older version. This allowed users<br />
to build older projects but only if they knew how to set the variable.<br />
In some cases CMake could generate an error about old behavior and<br />
tell the user to set the variable but in other cases it would silently<br />
fail or produce errors not mentioning the variable.<br />
<br />
The main problem with the <code>CMAKE_BACKWARDS_COMPATIBILITY</code><br />
was that it did not distinguish between a user trying to build someone<br />
else's project and that project's author. Only project authors should<br />
be required to do anything that changes how their project builds with<br />
new CMake versions. The CMake Policy mechanism addresses this issue.<br />
<br />
The CMake Policy mechanism was introduced in version CMake 2.6. For<br />
maximum compatibility CMake does not try to retroactively convert<br />
behavior changes introduced in versions 2.4 or lower into policies.<br />
Instead policy <code>CMP0001</code> decides whether or not to support<br />
2.4-style compatibility. It's OLD behavior is to present<br />
<code>CMAKE_BACKWARDS_COMPATIBILITY</code> and check for settings<br />
lower than 2.4. It's NEW behavior is to not add<br />
<code>CMAKE_BACKWARDS_COMPATIBILITY</code> and not check its value<br />
therefore removing all compatibility with versions lower than 2.4.<br />
<br />
Since all policies are introduced in CMake version 2.6 or later it<br />
does not make sense to allow a policy version lower than 2.4 to be<br />
set. Therefore the <code>cmake_policy</code> command's VERSION<br />
argument may not be lower than 2.4. Similarly,<br />
<code>cmake_minimum_required</code> will never set the policy version<br />
lower than 2.4 no matter what version is specified. This allows<br />
existing projects to automatically build with the old-style<br />
compatibility rules.<br />
<br />
=Updating a Project for a new CMake Version=<br />
<br />
When a CMake release introduces new policies it may generate warnings<br />
for some existing projects. These warnings indicate that changes to<br />
the project may need to be made to deal correctly with the new<br />
policies. While old releases of the project can continue to build<br />
with the warnings the project development tree should be updated to<br />
take the new policies into account.<br />
<br />
There are two approaches to updating a tree: one-shot and incremental. Which one is easier depends on the size of the project and what new policies produce warnings.<br />
<br />
==One-Shot Approach==<br />
<br />
The simplest approach to updating a project for a new version of CMake<br />
is simply to change the policy version set at the top of the project,<br />
try building with the new CMake version, and fix problems. For<br />
example, to update a project to build with CMake 2.6 one might write<br />
<br />
cmake_minimum_required(VERSION 2.6)<br />
<br />
at the beginning of the top-level <code>CMakeLists.txt</code> file.<br />
This tells CMake to use the NEW behavior for every policy introduced<br />
in CMake 2.6 and below. When building this project with CMake 2.6 no<br />
warnings will be produced about policies because it knows of no<br />
policies introduced in later versions. However, if the project was<br />
depending on the OLD behavior of a policy it may not build since CMake<br />
now uses the NEW behavior without warning. It is up to the project<br />
author who added the policy version line to fix these issues.<br />
<br />
==Incremental Approach==<br />
<br />
Another approach to updating a project for a new version of CMake is<br />
to deal with each warning one-by-one. An advantage of this approach<br />
is that the project will continue to build throughout the process so<br />
the changes can be made incrementally.<br />
<br />
When CMake encounters a situation where it needs to know whether to<br />
use the OLD or NEW behavior for a policy it checks whether the project<br />
has set the policy. If the policy is set CMake silently uses the<br />
corresponding behavior. If the policy is not set CMake uses the OLD<br />
behavior but warns that the policy is not set.<br />
<br />
In many cases the warning message will point at the exact line of code<br />
in the <code>CMakeLists.txt</code> files that produces the warning.<br />
In some cases the situation cannot be diagnosed until CMake is<br />
generating the native build system rules for the project so the<br />
warning will not include explicit context information. In these cases<br />
CMake will try to provide some information about where code may need<br />
to be changed. The documentation for these "generation-time" policies<br />
should indicate the point in the project code at which the policy<br />
should be set to take effect.<br />
<br />
In order to incrementally update a project one warning should be<br />
addressed at a time. Several cases may occur.<br />
<br />
===Silence a Warning When Code is Correct===<br />
<br />
Many policy warnings may be produced simply because the project has<br />
not set the policy even though the project may work correctly with the<br />
NEW behavior (there is no way for CMake to know the difference). For<br />
a warning about some policy <code>CMP<''NNNN''></code> one may check<br />
whether this is the case by adding<br />
<br />
cmake_policy(SET CMP<''NNNN''> NEW)<br />
<br />
to the top of the project and trying to build it. If the project<br />
builds correctly with the new behavior one may move on to the next<br />
policy warning. If the project does not build correctly one of the<br />
other cases may apply.<br />
<br />
===Silence a Warning Without Updating Code===<br />
<br />
One may suppress all instances of a warning<br />
<code>CMP<''NNNN''></code> by adding<br />
<br />
cmake_policy(SET CMP<''NNNN''> OLD)<br />
<br />
at the top of a project. However, we encourage project authors to<br />
update their code to work with the NEW behavior for all policies.<br />
This is especially important because versions of CMake in the<br />
(distant) future may remove support for the OLD behavior and produce<br />
an error for projects requesting it (which tells the user to get an<br />
older CMake to build the project).<br />
<br />
===Silence a Warning by Updating Code===<br />
<br />
When a project does not work correctly with the NEW behavior for a<br />
policy its code needs to be updated. In order to deal with a warning<br />
for some policy <code>CMP<''NNNN''></code> one may add<br />
<br />
cmake_policy(SET CMP<''NNNN''> NEW)<br />
<br />
at the top of the project and then fix the code to work with the NEW<br />
behavior.<br />
<br />
If many instances of the warning occur fixing all of them<br />
simultaneously may be too difficult. Instead a developer may fix one<br />
at a time. This may be done using the PUSH/POP signatures of the<br />
<code>cmake_policy</code> command:<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP<''NNNN''> NEW)<br />
# ... code updated for new policy behavior ...<br />
cmake_policy(POP)<br />
<br />
This will request NEW behavior for a small region of code that has<br />
been fixed. Other instances of the policy warning may still appear<br />
and must be fixed separately.<br />
<br />
===Updating the Project Policy Version===<br />
<br />
After addressing all policy warnings and getting the project to build<br />
cleanly with the new CMake version one step remains. The policy<br />
version set at the top of the project should now be updated to match<br />
the new CMake version, just as in the one-shot approach above. For<br />
example, after updating a project to build cleanly with CMake 2.6 one<br />
may update the top of the project with the line<br />
<br />
cmake_minimum_required(VERSION 2.6)<br />
<br />
or<br />
<br />
cmake_policy(VERSION 2.6)<br />
<br />
This will set all policies introduced in CMake 2.6 or below to use NEW<br />
behavior. Then one may sweep through the rest of the code and remove<br />
all the calls to the <code>cmake_policy</code> command used to request<br />
NEW behavior incrementally. The end result should look the same as<br />
the one-shot approach above but could be attained step-by-step.</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake_Policies_Design_Discussion&diff=11735CMake Policies Design Discussion2008-02-26T15:59:04Z<p>Martink: /* Proposed Solution */</p>
<hr />
<div>This page describes a proposal for a formal backwards/forwards compatibility feature.<br />
<br />
=Motivating Examples=<br />
<br />
==The ADD_DEFINITIONS Command==<br />
<br />
Consider code such as<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
which tries to add the option<br />
<br />
-DFOO=\"hello\ world\"<br />
<br />
to the compile command line. The code works in CMake 2.4's <code>Unix Makefiles</code> generator and produces a definition as if<br />
<br />
#define FOO "hello world"<br />
<br />
appeared in the source code. It works only because of the way the makefile generator happens to place the definition string in the command line. It may not work with the VS IDE generators.<br />
In CMake HEAD we provide the <code>COMPILE_DEFINITIONS</code> directory property so that one may write<br />
<br />
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "FOO=\"hello world\"")<br />
<br />
to get the correct behavior on all generators. Since CMake HEAD contains the appropriate escaping support it is desirable to allow the user to write<br />
<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
and get the expected behavior. Unfortunately if we were to start escaping the definitions given to <code>add_definitions</code> we would break compatibility with projects that are already adding their own escapes. In hindsight we should have either supported escapes from the beginning or make the command give an error that the definition value is not supported, but it is too late now.<br />
A similar problem appears in the <code>add_custom_command</code> command where support for properly escaping all arguments was added late. The solution currently used by that command is to require the user to add a <code>VERBATIM</code> argument to the command to get proper escaping. Using that solution for <code>add_definitions</code> would make the user write<br />
<br />
add_definitions(VERBATIM "-DFOO=\"hello world\"")<br />
<br />
just to get CMake to do the right thing. For compatibility CMake would have to implement the wrong behavior by default forever.<br />
<br />
==Missing Link Directories==<br />
<br />
Projects used to be able to write this (wrong) code and it would work by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect <br />
because it asks CMake to link to <code>B</code> but does not provide the proper <br />
linker search path for it. It used to work by accident because the <br />
<code>-L/path/to</code> would get added as part of the implementation of linking to <br />
A. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
Currently we provide the <code>CMAKE_OLD_LINK_PATHS</code> variable to allow projects or users to quickly work around the problem. Full compatibility would require us to support thie behavior by default forever. That would allow new projects to be written with the same bug.<br />
<br />
An alternative is to require all libraries to be linked via full path (where target names are expanded automatically). Whenever a non-full-path is given we could produce a warning that tells the user to start using <code>find_library</code> or something like that but then implement the old linker search path computation for compatibility. It is desirable to let projects that have been updated for newer CMake versions tell CMake that they know what they are doing and to not warn or use the compatibility behavior.<br />
<br />
=Proposed Solution=<br />
<br />
We propose the following solution to this problem.<br />
<br />
Each change that introduces a compatibility issue is assigned a new identification number (like CM00001 or something). Then we try to detect cases in user code where it '''might''' be an issue and deal with it. We can maintain in the implementation of CMake a mapping from feature id to a rule to deal with the issue when encountered. The possible means of dealing with such cases are:<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Rule !! Behavior !! Meaning !! Default?<br />
|-<br />
| QUIET || old || Project suppresses the diagnostic || only in special cases<br />
|-<br />
| WARN || old || Emit warning when case is encountered || most cases<br />
|-<br />
| ERROR || none || Emit error when case is encountered || only for cases that can be detected with no false positives<br />
|-<br />
| FIXED || new || Project declares the case has been resolved || never? distant future release after creation of issue?<br />
|-<br />
| REQUIRED || new || Must use the new behavior || future CMake release, compatibility can be dropped but still checked for<br />
|-<br />
| REQUIRED_NO_CHECK || new || Must use the new behavior || future CMake release, compatibility is dropped as well as the code to check if the file uses this issue<br />
|}<br />
<br />
Several releases after a compatibility issue has been introduced we can remove implementation of support for the old behavior and set it to "REQUIRED" internally that requires a project to declare the issue FIXED or to be of a CMake version such that we know it would have generated warning. See the feature lifespan example.<br />
<br />
==Proposed CMAKE_FEATURE Command==<br />
<br />
We will introduce a new command for projects to use for setting the rule for each feature.<br />
<br />
The signature<br />
<br />
cmake_feature(SET <feature-id> <QUIET|WARN|ERROR|FIXED>)<br />
<br />
sets the current rule for the feature. It is an error to specify a feature id that does not exist (because it might refer to a feature id introduced in a future version of CMake).<br />
<br />
The signature<br />
<br />
cmake_feature(VERSION <major[.minor[.patch]]>)<br />
<br />
sets the current rules for all features to match the preferred (new) behavior as of a given CMake version and also requires the running CMake to be at least that version. The <code>cmake_minimum_required(VERSION)</code> command can do something similar (but use of new commands versus fixing other issues are distinct cases so the defaults may need to be different).<br />
<br />
The signature<br />
<br />
cmake_feature(PUSH|POP)<br />
<br />
pushes or pops the current feature state on a stack. The stack is automatically pushed/popped when entering a new directory (under <code>add_subdirectory</code> for example). Within a directory the number of PUSH and POP calls must match or it is an error. This signature is useful in a .cmake script meant for inclusion in other projects. It could write<br />
<br />
cmake_feature(PUSH)<br />
cmake_feature(SET CMF_00001 FIXED)<br />
... code using CMF_00001 ...<br />
cmake_feature(POP)<br />
<br />
The command could also provide an alias for each feature id that is more human readable:<br />
<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
<br />
==Examples==<br />
<br />
Let's define a few example feature ids<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Id !! Alias !! Description<br />
|-<br />
| CMF_00001 || CMF_ESCAPE_DEFINITIONS || Enable proper escaping of definitions added with ADD_DEFINITIONS<br />
|-<br />
| CMF_00002 || CMF_ESCAPE_CUSTOM_COMMANDS || Enable proper escaping of custom command lines with ADD_CUSTOM_COMMAND, make VERBATIM argument an error<br />
|-<br />
| CMF_00003 || CMF_NO_AUTOMATIC_LINK_PATHS || Disable generation of compatibility -L options on link lines<br />
|}<br />
<br />
The code<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
can now produce a warning CMF_00001 that CMake does not know whether to escape the definition (only when a non-trivial value is given).<br />
<br />
The project may suppress the warning in their release branch:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS QUIET)<br />
...<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
or fix the code:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
...<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
Either way CMake knows exactly how to handle the code and does not need to warn.<br />
<br />
Similarly, the code<br />
<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
may now produce a warning CMF_00002 that CMake does not know whether to escape the command.<br />
The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_CUSTOM_COMMANDS FIXED)<br />
...<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
to get rid of the warning and use proper escaping.<br />
<br />
The code<br />
<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
may now produce a warning CMF_00003 that library B may not have the correct link directory specified but then generate -L/path/to anyway. The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_NO_AUTOMATIC_LINK_PATHS FIXED)<br />
...<br />
link_directories(/path/to)<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
Once the project has fixed all issues related to upgrading to CMake 2.6 it can just write<br />
<br />
project(FOO)<br />
cmake_feature(VERSION 2.6)<br />
<br />
to get all the updated behavior.<br />
<br />
==Feature Lifespan Example==<br />
<br />
Using the CMF_00001 || CMF_ESCAPE_DEFINITIONS example above let's examine how it would work. In CMake 2.4 definitions had to be escaped by the user which probably does not work on MSVC etc. So in 2.6 we want to start switching over to having CMake handle the escaping. <br />
<br />
* CMake 2.4: old behavior, issue CMF_0001 does not even exist<br />
<br />
* CMake 2.6: issue CMF_0001 is created and set to WARN and version number 2.6. By default old projects will still work but will receive a warning if they use this feature. The issue can be either made QUIET <code>cmake_feature(SET CMF_0001 QUIET)</code> with no other changes to the CMakeLists file or the issue can be fixed by changing their code and setting it to FIXED <code>cmake_feature(SET CMF_0001 FIXED)</code>. Or they can ignore it and just live with the warnings.<br />
<br />
* CMake 2.8: Nothing changes, stays as a warning<br />
<br />
* CMake 2.10: We change the default value of issue CMF_0001 to REQUIRED. Now if the user's CMakeLists file sets the issue to QUITE or WARN CMake will produce an error indicating that that is no longer an option for feature CMF_0001 and the issue must be fixed or an earlier version of CMake used. But what if the CMakeList file does not specify anything about CMF_0001? In that case we do nothing if the feature is not used. If it is used, we look at the VERSION the CMakeList file was written to. If it was written to CMake 2.6 or later we assume it is fixed. If it is written to an earlier version we assume it is not fixed and report an error.<br />
<br />
* CMake 2.12: We change the default value of issue CMF_0001 to REQUIRED_NO_CHECK. This is the same as required if the CMakeList file specifies anything about CMF_0001. But if it does not, then we produce an error if the CMakeLists file was written to CMake 2.4 or earlier. We do not check to see if they are using the feature at all. That code has been removed. They must have specified that they are using CMake 2.6 or later via cmake_minimum_required(2.6) or cmake_feature(VERSION 2.6) or later.<br />
<br />
==Discussion==<br />
<br />
This solution has the following advantages:<br />
<br />
* All compatibility issues are documented and given unique identifiers<br />
** Documentation can include association with CMake version ranges (when introduced, when REQUIRED, etc.)<br />
* We can be more aggressive about detecting cases without worrying about false positives because it is just a warning<br />
* When generating a warning or error message we can reference the feature id and tell the user what to do<br />
* Projects can be converted to newer CMake features incrementally<br />
* Project authors will be motivated by the warnings to update their code, but it will build for users without extra work<br />
* Code written that does not hit one of these issues will work without any special declarations<br />
** The hello-world example does not need to show version specification<br />
* We have an exit-path to remove support for a compatibility feature eventually<br />
** Make projects rule to FIXED explicitly or via VERSION specification<br />
* Any compatibility bug introduced accidentally and reported by a user can be fixed in CMake by converting it to one of these issues<br />
<br />
==Alternative Names==<br />
<br />
I'm not happy with the current naming. Perhaps the command could be <code>cmake_behavior</code> and <code>QUIET|WARN|ERROR|FIXED</code> should be <code>OLD|WARN|ERROR|NEW</code>:<br />
<br />
cmake_behavior(PUSH)<br />
cmake_behavior(SET CMB_00001 OLD) # request old behavior<br />
cmake_behavior(SET CMB_00001 WARN) # request old behavior with warning<br />
cmake_behavior(SET CMB_00001 ERROR) # request error when case is encountered<br />
cmake_behavior(SET CMB_00001 NEW) # request new behavior<br />
cmake_behavior(VERSION 2.6) # request new behavior as of CMake 2.6<br />
cmake_behavior(POP)<br />
<br />
Or perhaps "<code>cmake_policy</code>"<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP_00001 OLD) # request old policy<br />
cmake_policy(SET CMP_00001 WARN) # request old policy with warning<br />
cmake_policy(SET CMP_00001 ERROR) # request error when case is encountered<br />
cmake_policy(SET CMP_00001 NEW) # request new policy<br />
cmake_policy(VERSION 2.6) # request new policy as of CMake 2.6<br />
cmake_policy(POP)</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake_Policies_Design_Discussion&diff=11734CMake Policies Design Discussion2008-02-26T15:56:36Z<p>Martink: /* Feature Lifespan Example */</p>
<hr />
<div>This page describes a proposal for a formal backwards/forwards compatibility feature.<br />
<br />
=Motivating Examples=<br />
<br />
==The ADD_DEFINITIONS Command==<br />
<br />
Consider code such as<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
which tries to add the option<br />
<br />
-DFOO=\"hello\ world\"<br />
<br />
to the compile command line. The code works in CMake 2.4's <code>Unix Makefiles</code> generator and produces a definition as if<br />
<br />
#define FOO "hello world"<br />
<br />
appeared in the source code. It works only because of the way the makefile generator happens to place the definition string in the command line. It may not work with the VS IDE generators.<br />
In CMake HEAD we provide the <code>COMPILE_DEFINITIONS</code> directory property so that one may write<br />
<br />
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "FOO=\"hello world\"")<br />
<br />
to get the correct behavior on all generators. Since CMake HEAD contains the appropriate escaping support it is desirable to allow the user to write<br />
<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
and get the expected behavior. Unfortunately if we were to start escaping the definitions given to <code>add_definitions</code> we would break compatibility with projects that are already adding their own escapes. In hindsight we should have either supported escapes from the beginning or make the command give an error that the definition value is not supported, but it is too late now.<br />
A similar problem appears in the <code>add_custom_command</code> command where support for properly escaping all arguments was added late. The solution currently used by that command is to require the user to add a <code>VERBATIM</code> argument to the command to get proper escaping. Using that solution for <code>add_definitions</code> would make the user write<br />
<br />
add_definitions(VERBATIM "-DFOO=\"hello world\"")<br />
<br />
just to get CMake to do the right thing. For compatibility CMake would have to implement the wrong behavior by default forever.<br />
<br />
==Missing Link Directories==<br />
<br />
Projects used to be able to write this (wrong) code and it would work by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect <br />
because it asks CMake to link to <code>B</code> but does not provide the proper <br />
linker search path for it. It used to work by accident because the <br />
<code>-L/path/to</code> would get added as part of the implementation of linking to <br />
A. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
Currently we provide the <code>CMAKE_OLD_LINK_PATHS</code> variable to allow projects or users to quickly work around the problem. Full compatibility would require us to support thie behavior by default forever. That would allow new projects to be written with the same bug.<br />
<br />
An alternative is to require all libraries to be linked via full path (where target names are expanded automatically). Whenever a non-full-path is given we could produce a warning that tells the user to start using <code>find_library</code> or something like that but then implement the old linker search path computation for compatibility. It is desirable to let projects that have been updated for newer CMake versions tell CMake that they know what they are doing and to not warn or use the compatibility behavior.<br />
<br />
=Proposed Solution=<br />
<br />
We propose the following solution to this problem.<br />
<br />
Each change that introduces a compatibility issue is assigned a new identification number (like CM00001 or something). Then we try to detect cases in user code where it '''might''' be an issue and deal with it. We can maintain in the implementation of CMake a mapping from feature id to a rule to deal with the issue when encountered. The possible means of dealing with such cases are:<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Rule !! Behavior !! Meaning !! Default?<br />
|-<br />
| QUIET || old || Project suppresses the diagnostic || only in special cases<br />
|-<br />
| WARN || old || Emit warning when case is encountered || most cases<br />
|-<br />
| ERROR || none || Emit error when case is encountered || only for cases that can be detected with no false positives<br />
|-<br />
| FIXED || new || Project declares the case has been resolved || never? distant future release after creation of issue?<br />
|-<br />
| REQUIRED || new || Must use the new behavior || future CMake release, compatibility can be dropped but still checked for<br />
|-<br />
| REQUIRED_NO_CHECK || new || Must use the new behavior || future CMake release, compatibility is dropped as well as the code to check for this issue<br />
|}<br />
<br />
Several releases after a compatibility issue has been introduced we can remove implementation of support for the old behavior and set it to "REQUIRED" internally that requires a project to declare the issue FIXED or to be of a CMake version such that we know it would have generated warning. See the feature lifespan example.<br />
<br />
==Proposed CMAKE_FEATURE Command==<br />
<br />
We will introduce a new command for projects to use for setting the rule for each feature.<br />
<br />
The signature<br />
<br />
cmake_feature(SET <feature-id> <QUIET|WARN|ERROR|FIXED>)<br />
<br />
sets the current rule for the feature. It is an error to specify a feature id that does not exist (because it might refer to a feature id introduced in a future version of CMake).<br />
<br />
The signature<br />
<br />
cmake_feature(VERSION <major[.minor[.patch]]>)<br />
<br />
sets the current rules for all features to match the preferred (new) behavior as of a given CMake version and also requires the running CMake to be at least that version. The <code>cmake_minimum_required(VERSION)</code> command can do something similar (but use of new commands versus fixing other issues are distinct cases so the defaults may need to be different).<br />
<br />
The signature<br />
<br />
cmake_feature(PUSH|POP)<br />
<br />
pushes or pops the current feature state on a stack. The stack is automatically pushed/popped when entering a new directory (under <code>add_subdirectory</code> for example). Within a directory the number of PUSH and POP calls must match or it is an error. This signature is useful in a .cmake script meant for inclusion in other projects. It could write<br />
<br />
cmake_feature(PUSH)<br />
cmake_feature(SET CMF_00001 FIXED)<br />
... code using CMF_00001 ...<br />
cmake_feature(POP)<br />
<br />
The command could also provide an alias for each feature id that is more human readable:<br />
<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
<br />
==Examples==<br />
<br />
Let's define a few example feature ids<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Id !! Alias !! Description<br />
|-<br />
| CMF_00001 || CMF_ESCAPE_DEFINITIONS || Enable proper escaping of definitions added with ADD_DEFINITIONS<br />
|-<br />
| CMF_00002 || CMF_ESCAPE_CUSTOM_COMMANDS || Enable proper escaping of custom command lines with ADD_CUSTOM_COMMAND, make VERBATIM argument an error<br />
|-<br />
| CMF_00003 || CMF_NO_AUTOMATIC_LINK_PATHS || Disable generation of compatibility -L options on link lines<br />
|}<br />
<br />
The code<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
can now produce a warning CMF_00001 that CMake does not know whether to escape the definition (only when a non-trivial value is given).<br />
<br />
The project may suppress the warning in their release branch:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS QUIET)<br />
...<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
or fix the code:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
...<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
Either way CMake knows exactly how to handle the code and does not need to warn.<br />
<br />
Similarly, the code<br />
<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
may now produce a warning CMF_00002 that CMake does not know whether to escape the command.<br />
The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_CUSTOM_COMMANDS FIXED)<br />
...<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
to get rid of the warning and use proper escaping.<br />
<br />
The code<br />
<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
may now produce a warning CMF_00003 that library B may not have the correct link directory specified but then generate -L/path/to anyway. The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_NO_AUTOMATIC_LINK_PATHS FIXED)<br />
...<br />
link_directories(/path/to)<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
Once the project has fixed all issues related to upgrading to CMake 2.6 it can just write<br />
<br />
project(FOO)<br />
cmake_feature(VERSION 2.6)<br />
<br />
to get all the updated behavior.<br />
<br />
==Feature Lifespan Example==<br />
<br />
Using the CMF_00001 || CMF_ESCAPE_DEFINITIONS example above let's examine how it would work. In CMake 2.4 definitions had to be escaped by the user which probably does not work on MSVC etc. So in 2.6 we want to start switching over to having CMake handle the escaping. <br />
<br />
* CMake 2.4: old behavior, issue CMF_0001 does not even exist<br />
<br />
* CMake 2.6: issue CMF_0001 is created and set to WARN and version number 2.6. By default old projects will still work but will receive a warning if they use this feature. The issue can be either made QUIET <code>cmake_feature(SET CMF_0001 QUIET)</code> with no other changes to the CMakeLists file or the issue can be fixed by changing their code and setting it to FIXED <code>cmake_feature(SET CMF_0001 FIXED)</code>. Or they can ignore it and just live with the warnings.<br />
<br />
* CMake 2.8: Nothing changes, stays as a warning<br />
<br />
* CMake 2.10: We change the default value of issue CMF_0001 to REQUIRED. Now if the user's CMakeLists file sets the issue to QUITE or WARN CMake will produce an error indicating that that is no longer an option for feature CMF_0001 and the issue must be fixed or an earlier version of CMake used. But what if the CMakeList file does not specify anything about CMF_0001? In that case we do nothing if the feature is not used. If it is used, we look at the VERSION the CMakeList file was written to. If it was written to CMake 2.6 or later we assume it is fixed. If it is written to an earlier version we assume it is not fixed and report an error.<br />
<br />
* CMake 2.12: We change the default value of issue CMF_0001 to REQUIRED_NO_CHECK. This is the same as required if the CMakeList file specifies anything about CMF_0001. But if it does not, then we produce an error if the CMakeLists file was written to CMake 2.4 or earlier. We do not check to see if they are using the feature at all. That code has been removed. They must have specified that they are using CMake 2.6 or later via cmake_minimum_required(2.6) or cmake_feature(VERSION 2.6) or later.<br />
<br />
==Discussion==<br />
<br />
This solution has the following advantages:<br />
<br />
* All compatibility issues are documented and given unique identifiers<br />
** Documentation can include association with CMake version ranges (when introduced, when REQUIRED, etc.)<br />
* We can be more aggressive about detecting cases without worrying about false positives because it is just a warning<br />
* When generating a warning or error message we can reference the feature id and tell the user what to do<br />
* Projects can be converted to newer CMake features incrementally<br />
* Project authors will be motivated by the warnings to update their code, but it will build for users without extra work<br />
* Code written that does not hit one of these issues will work without any special declarations<br />
** The hello-world example does not need to show version specification<br />
* We have an exit-path to remove support for a compatibility feature eventually<br />
** Make projects rule to FIXED explicitly or via VERSION specification<br />
* Any compatibility bug introduced accidentally and reported by a user can be fixed in CMake by converting it to one of these issues<br />
<br />
==Alternative Names==<br />
<br />
I'm not happy with the current naming. Perhaps the command could be <code>cmake_behavior</code> and <code>QUIET|WARN|ERROR|FIXED</code> should be <code>OLD|WARN|ERROR|NEW</code>:<br />
<br />
cmake_behavior(PUSH)<br />
cmake_behavior(SET CMB_00001 OLD) # request old behavior<br />
cmake_behavior(SET CMB_00001 WARN) # request old behavior with warning<br />
cmake_behavior(SET CMB_00001 ERROR) # request error when case is encountered<br />
cmake_behavior(SET CMB_00001 NEW) # request new behavior<br />
cmake_behavior(VERSION 2.6) # request new behavior as of CMake 2.6<br />
cmake_behavior(POP)<br />
<br />
Or perhaps "<code>cmake_policy</code>"<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP_00001 OLD) # request old policy<br />
cmake_policy(SET CMP_00001 WARN) # request old policy with warning<br />
cmake_policy(SET CMP_00001 ERROR) # request error when case is encountered<br />
cmake_policy(SET CMP_00001 NEW) # request new policy<br />
cmake_policy(VERSION 2.6) # request new policy as of CMake 2.6<br />
cmake_policy(POP)</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake_Policies_Design_Discussion&diff=11733CMake Policies Design Discussion2008-02-26T15:51:11Z<p>Martink: /* Feature Lifespan Example */</p>
<hr />
<div>This page describes a proposal for a formal backwards/forwards compatibility feature.<br />
<br />
=Motivating Examples=<br />
<br />
==The ADD_DEFINITIONS Command==<br />
<br />
Consider code such as<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
which tries to add the option<br />
<br />
-DFOO=\"hello\ world\"<br />
<br />
to the compile command line. The code works in CMake 2.4's <code>Unix Makefiles</code> generator and produces a definition as if<br />
<br />
#define FOO "hello world"<br />
<br />
appeared in the source code. It works only because of the way the makefile generator happens to place the definition string in the command line. It may not work with the VS IDE generators.<br />
In CMake HEAD we provide the <code>COMPILE_DEFINITIONS</code> directory property so that one may write<br />
<br />
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "FOO=\"hello world\"")<br />
<br />
to get the correct behavior on all generators. Since CMake HEAD contains the appropriate escaping support it is desirable to allow the user to write<br />
<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
and get the expected behavior. Unfortunately if we were to start escaping the definitions given to <code>add_definitions</code> we would break compatibility with projects that are already adding their own escapes. In hindsight we should have either supported escapes from the beginning or make the command give an error that the definition value is not supported, but it is too late now.<br />
A similar problem appears in the <code>add_custom_command</code> command where support for properly escaping all arguments was added late. The solution currently used by that command is to require the user to add a <code>VERBATIM</code> argument to the command to get proper escaping. Using that solution for <code>add_definitions</code> would make the user write<br />
<br />
add_definitions(VERBATIM "-DFOO=\"hello world\"")<br />
<br />
just to get CMake to do the right thing. For compatibility CMake would have to implement the wrong behavior by default forever.<br />
<br />
==Missing Link Directories==<br />
<br />
Projects used to be able to write this (wrong) code and it would work by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect <br />
because it asks CMake to link to <code>B</code> but does not provide the proper <br />
linker search path for it. It used to work by accident because the <br />
<code>-L/path/to</code> would get added as part of the implementation of linking to <br />
A. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
Currently we provide the <code>CMAKE_OLD_LINK_PATHS</code> variable to allow projects or users to quickly work around the problem. Full compatibility would require us to support thie behavior by default forever. That would allow new projects to be written with the same bug.<br />
<br />
An alternative is to require all libraries to be linked via full path (where target names are expanded automatically). Whenever a non-full-path is given we could produce a warning that tells the user to start using <code>find_library</code> or something like that but then implement the old linker search path computation for compatibility. It is desirable to let projects that have been updated for newer CMake versions tell CMake that they know what they are doing and to not warn or use the compatibility behavior.<br />
<br />
=Proposed Solution=<br />
<br />
We propose the following solution to this problem.<br />
<br />
Each change that introduces a compatibility issue is assigned a new identification number (like CM00001 or something). Then we try to detect cases in user code where it '''might''' be an issue and deal with it. We can maintain in the implementation of CMake a mapping from feature id to a rule to deal with the issue when encountered. The possible means of dealing with such cases are:<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Rule !! Behavior !! Meaning !! Default?<br />
|-<br />
| QUIET || old || Project suppresses the diagnostic || only in special cases<br />
|-<br />
| WARN || old || Emit warning when case is encountered || most cases<br />
|-<br />
| ERROR || none || Emit error when case is encountered || only for cases that can be detected with no false positives<br />
|-<br />
| FIXED || new || Project declares the case has been resolved || never? distant future release after creation of issue?<br />
|-<br />
| REQUIRED || new || Must use the new behavior || future CMake release, compatibility can be dropped but still checked for<br />
|-<br />
| REQUIRED_NO_CHECK || new || Must use the new behavior || future CMake release, compatibility is dropped as well as the code to check for this issue<br />
|}<br />
<br />
Several releases after a compatibility issue has been introduced we can remove implementation of support for the old behavior and set it to "REQUIRED" internally that requires a project to declare the issue FIXED or to be of a CMake version such that we know it would have generated warning. See the feature lifespan example.<br />
<br />
==Proposed CMAKE_FEATURE Command==<br />
<br />
We will introduce a new command for projects to use for setting the rule for each feature.<br />
<br />
The signature<br />
<br />
cmake_feature(SET <feature-id> <QUIET|WARN|ERROR|FIXED>)<br />
<br />
sets the current rule for the feature. It is an error to specify a feature id that does not exist (because it might refer to a feature id introduced in a future version of CMake).<br />
<br />
The signature<br />
<br />
cmake_feature(VERSION <major[.minor[.patch]]>)<br />
<br />
sets the current rules for all features to match the preferred (new) behavior as of a given CMake version and also requires the running CMake to be at least that version. The <code>cmake_minimum_required(VERSION)</code> command can do something similar (but use of new commands versus fixing other issues are distinct cases so the defaults may need to be different).<br />
<br />
The signature<br />
<br />
cmake_feature(PUSH|POP)<br />
<br />
pushes or pops the current feature state on a stack. The stack is automatically pushed/popped when entering a new directory (under <code>add_subdirectory</code> for example). Within a directory the number of PUSH and POP calls must match or it is an error. This signature is useful in a .cmake script meant for inclusion in other projects. It could write<br />
<br />
cmake_feature(PUSH)<br />
cmake_feature(SET CMF_00001 FIXED)<br />
... code using CMF_00001 ...<br />
cmake_feature(POP)<br />
<br />
The command could also provide an alias for each feature id that is more human readable:<br />
<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
<br />
==Examples==<br />
<br />
Let's define a few example feature ids<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Id !! Alias !! Description<br />
|-<br />
| CMF_00001 || CMF_ESCAPE_DEFINITIONS || Enable proper escaping of definitions added with ADD_DEFINITIONS<br />
|-<br />
| CMF_00002 || CMF_ESCAPE_CUSTOM_COMMANDS || Enable proper escaping of custom command lines with ADD_CUSTOM_COMMAND, make VERBATIM argument an error<br />
|-<br />
| CMF_00003 || CMF_NO_AUTOMATIC_LINK_PATHS || Disable generation of compatibility -L options on link lines<br />
|}<br />
<br />
The code<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
can now produce a warning CMF_00001 that CMake does not know whether to escape the definition (only when a non-trivial value is given).<br />
<br />
The project may suppress the warning in their release branch:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS QUIET)<br />
...<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
or fix the code:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
...<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
Either way CMake knows exactly how to handle the code and does not need to warn.<br />
<br />
Similarly, the code<br />
<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
may now produce a warning CMF_00002 that CMake does not know whether to escape the command.<br />
The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_CUSTOM_COMMANDS FIXED)<br />
...<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
to get rid of the warning and use proper escaping.<br />
<br />
The code<br />
<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
may now produce a warning CMF_00003 that library B may not have the correct link directory specified but then generate -L/path/to anyway. The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_NO_AUTOMATIC_LINK_PATHS FIXED)<br />
...<br />
link_directories(/path/to)<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
Once the project has fixed all issues related to upgrading to CMake 2.6 it can just write<br />
<br />
project(FOO)<br />
cmake_feature(VERSION 2.6)<br />
<br />
to get all the updated behavior.<br />
<br />
==Feature Lifespan Example==<br />
<br />
Using the CMF_00001 || CMF_ESCAPE_DEFINITIONS example above let's examine how it would work. In CMake 2.4 definitions had to be escaped by the user which probably does not work on MSVC etc. So in 2.6 we want to start switching over to having CMake handle the escaping. <br />
<br />
* CMake 2.4: old behavior, issue CMF_0001 does not even exist<br />
<br />
* CMake 2.6: issue CMF_0001 is created and set to WARN and version number 2.6. By default old projects will still work but will receive a warning. The issue can be either made QUIET <code>cmake_feature(SET CMF_0001 QUIET)</code> with no other changes to the CMakeLists file or the issue can be fixed by changing their code and setting it to FIXED <code>cmake_feature(SET CMF_0001 FIXED)</code>. Or they can ignore it and just live with the warnings.<br />
<br />
* CMake 2.8: Nothing changes, stays as a warning<br />
<br />
* CMake 2.10: We change the default value of issue CMF_0001 to REQUIRED. Now if the user's CMakeLists file sets the issue to QUITE or WARN CMake will produce an error indicating that that is no longer an option for feature CMF_0001 and the issue must be fixed or an earlier version of CMake used. But what if the CMakeList file does not specify anything about CMF_0001? In that case we do nothing if the feature is not used. If it is used, we look at the VERSION the CMakeList file was written to. If it was written to CMake 2.6 or later we assume it is fixed. If it is written to an earlier version we assume it is not fixed and report an error.<br />
<br />
* CMake 2.12: We change the default value of issue CMF_0001 to REQUIRED_NO_CHECK. This is the same as required if the CMakeList file specifies anything about CMF_0001. But if it does not, then we produce an error if the CMakeLists file was written to CMake 2.4 or earlier. We do not check to see if they are using the feature at all. That code has been removed. They must have specified that they are using CMake 2.6 or later via cmake_minimum_required(2.6) or cmake_feature(VERSION 2.6) or later.<br />
<br />
==Discussion==<br />
<br />
This solution has the following advantages:<br />
<br />
* All compatibility issues are documented and given unique identifiers<br />
** Documentation can include association with CMake version ranges (when introduced, when REQUIRED, etc.)<br />
* We can be more aggressive about detecting cases without worrying about false positives because it is just a warning<br />
* When generating a warning or error message we can reference the feature id and tell the user what to do<br />
* Projects can be converted to newer CMake features incrementally<br />
* Project authors will be motivated by the warnings to update their code, but it will build for users without extra work<br />
* Code written that does not hit one of these issues will work without any special declarations<br />
** The hello-world example does not need to show version specification<br />
* We have an exit-path to remove support for a compatibility feature eventually<br />
** Make projects rule to FIXED explicitly or via VERSION specification<br />
* Any compatibility bug introduced accidentally and reported by a user can be fixed in CMake by converting it to one of these issues<br />
<br />
==Alternative Names==<br />
<br />
I'm not happy with the current naming. Perhaps the command could be <code>cmake_behavior</code> and <code>QUIET|WARN|ERROR|FIXED</code> should be <code>OLD|WARN|ERROR|NEW</code>:<br />
<br />
cmake_behavior(PUSH)<br />
cmake_behavior(SET CMB_00001 OLD) # request old behavior<br />
cmake_behavior(SET CMB_00001 WARN) # request old behavior with warning<br />
cmake_behavior(SET CMB_00001 ERROR) # request error when case is encountered<br />
cmake_behavior(SET CMB_00001 NEW) # request new behavior<br />
cmake_behavior(VERSION 2.6) # request new behavior as of CMake 2.6<br />
cmake_behavior(POP)<br />
<br />
Or perhaps "<code>cmake_policy</code>"<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP_00001 OLD) # request old policy<br />
cmake_policy(SET CMP_00001 WARN) # request old policy with warning<br />
cmake_policy(SET CMP_00001 ERROR) # request error when case is encountered<br />
cmake_policy(SET CMP_00001 NEW) # request new policy<br />
cmake_policy(VERSION 2.6) # request new policy as of CMake 2.6<br />
cmake_policy(POP)</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake_Policies_Design_Discussion&diff=11732CMake Policies Design Discussion2008-02-26T15:49:48Z<p>Martink: /* Feature Lifespan Example */</p>
<hr />
<div>This page describes a proposal for a formal backwards/forwards compatibility feature.<br />
<br />
=Motivating Examples=<br />
<br />
==The ADD_DEFINITIONS Command==<br />
<br />
Consider code such as<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
which tries to add the option<br />
<br />
-DFOO=\"hello\ world\"<br />
<br />
to the compile command line. The code works in CMake 2.4's <code>Unix Makefiles</code> generator and produces a definition as if<br />
<br />
#define FOO "hello world"<br />
<br />
appeared in the source code. It works only because of the way the makefile generator happens to place the definition string in the command line. It may not work with the VS IDE generators.<br />
In CMake HEAD we provide the <code>COMPILE_DEFINITIONS</code> directory property so that one may write<br />
<br />
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "FOO=\"hello world\"")<br />
<br />
to get the correct behavior on all generators. Since CMake HEAD contains the appropriate escaping support it is desirable to allow the user to write<br />
<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
and get the expected behavior. Unfortunately if we were to start escaping the definitions given to <code>add_definitions</code> we would break compatibility with projects that are already adding their own escapes. In hindsight we should have either supported escapes from the beginning or make the command give an error that the definition value is not supported, but it is too late now.<br />
A similar problem appears in the <code>add_custom_command</code> command where support for properly escaping all arguments was added late. The solution currently used by that command is to require the user to add a <code>VERBATIM</code> argument to the command to get proper escaping. Using that solution for <code>add_definitions</code> would make the user write<br />
<br />
add_definitions(VERBATIM "-DFOO=\"hello world\"")<br />
<br />
just to get CMake to do the right thing. For compatibility CMake would have to implement the wrong behavior by default forever.<br />
<br />
==Missing Link Directories==<br />
<br />
Projects used to be able to write this (wrong) code and it would work by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect <br />
because it asks CMake to link to <code>B</code> but does not provide the proper <br />
linker search path for it. It used to work by accident because the <br />
<code>-L/path/to</code> would get added as part of the implementation of linking to <br />
A. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
Currently we provide the <code>CMAKE_OLD_LINK_PATHS</code> variable to allow projects or users to quickly work around the problem. Full compatibility would require us to support thie behavior by default forever. That would allow new projects to be written with the same bug.<br />
<br />
An alternative is to require all libraries to be linked via full path (where target names are expanded automatically). Whenever a non-full-path is given we could produce a warning that tells the user to start using <code>find_library</code> or something like that but then implement the old linker search path computation for compatibility. It is desirable to let projects that have been updated for newer CMake versions tell CMake that they know what they are doing and to not warn or use the compatibility behavior.<br />
<br />
=Proposed Solution=<br />
<br />
We propose the following solution to this problem.<br />
<br />
Each change that introduces a compatibility issue is assigned a new identification number (like CM00001 or something). Then we try to detect cases in user code where it '''might''' be an issue and deal with it. We can maintain in the implementation of CMake a mapping from feature id to a rule to deal with the issue when encountered. The possible means of dealing with such cases are:<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Rule !! Behavior !! Meaning !! Default?<br />
|-<br />
| QUIET || old || Project suppresses the diagnostic || only in special cases<br />
|-<br />
| WARN || old || Emit warning when case is encountered || most cases<br />
|-<br />
| ERROR || none || Emit error when case is encountered || only for cases that can be detected with no false positives<br />
|-<br />
| FIXED || new || Project declares the case has been resolved || never? distant future release after creation of issue?<br />
|-<br />
| REQUIRED || new || Must use the new behavior || future CMake release, compatibility can be dropped but still checked for<br />
|-<br />
| REQUIRED_NO_CHECK || new || Must use the new behavior || future CMake release, compatibility is dropped as well as the code to check for this issue<br />
|}<br />
<br />
Several releases after a compatibility issue has been introduced we can remove implementation of support for the old behavior and set it to "REQUIRED" internally that requires a project to declare the issue FIXED or to be of a CMake version such that we know it would have generated warning. See the feature lifespan example.<br />
<br />
==Proposed CMAKE_FEATURE Command==<br />
<br />
We will introduce a new command for projects to use for setting the rule for each feature.<br />
<br />
The signature<br />
<br />
cmake_feature(SET <feature-id> <QUIET|WARN|ERROR|FIXED>)<br />
<br />
sets the current rule for the feature. It is an error to specify a feature id that does not exist (because it might refer to a feature id introduced in a future version of CMake).<br />
<br />
The signature<br />
<br />
cmake_feature(VERSION <major[.minor[.patch]]>)<br />
<br />
sets the current rules for all features to match the preferred (new) behavior as of a given CMake version and also requires the running CMake to be at least that version. The <code>cmake_minimum_required(VERSION)</code> command can do something similar (but use of new commands versus fixing other issues are distinct cases so the defaults may need to be different).<br />
<br />
The signature<br />
<br />
cmake_feature(PUSH|POP)<br />
<br />
pushes or pops the current feature state on a stack. The stack is automatically pushed/popped when entering a new directory (under <code>add_subdirectory</code> for example). Within a directory the number of PUSH and POP calls must match or it is an error. This signature is useful in a .cmake script meant for inclusion in other projects. It could write<br />
<br />
cmake_feature(PUSH)<br />
cmake_feature(SET CMF_00001 FIXED)<br />
... code using CMF_00001 ...<br />
cmake_feature(POP)<br />
<br />
The command could also provide an alias for each feature id that is more human readable:<br />
<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
<br />
==Examples==<br />
<br />
Let's define a few example feature ids<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Id !! Alias !! Description<br />
|-<br />
| CMF_00001 || CMF_ESCAPE_DEFINITIONS || Enable proper escaping of definitions added with ADD_DEFINITIONS<br />
|-<br />
| CMF_00002 || CMF_ESCAPE_CUSTOM_COMMANDS || Enable proper escaping of custom command lines with ADD_CUSTOM_COMMAND, make VERBATIM argument an error<br />
|-<br />
| CMF_00003 || CMF_NO_AUTOMATIC_LINK_PATHS || Disable generation of compatibility -L options on link lines<br />
|}<br />
<br />
The code<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
can now produce a warning CMF_00001 that CMake does not know whether to escape the definition (only when a non-trivial value is given).<br />
<br />
The project may suppress the warning in their release branch:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS QUIET)<br />
...<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
or fix the code:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
...<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
Either way CMake knows exactly how to handle the code and does not need to warn.<br />
<br />
Similarly, the code<br />
<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
may now produce a warning CMF_00002 that CMake does not know whether to escape the command.<br />
The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_CUSTOM_COMMANDS FIXED)<br />
...<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
to get rid of the warning and use proper escaping.<br />
<br />
The code<br />
<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
may now produce a warning CMF_00003 that library B may not have the correct link directory specified but then generate -L/path/to anyway. The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_NO_AUTOMATIC_LINK_PATHS FIXED)<br />
...<br />
link_directories(/path/to)<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
Once the project has fixed all issues related to upgrading to CMake 2.6 it can just write<br />
<br />
project(FOO)<br />
cmake_feature(VERSION 2.6)<br />
<br />
to get all the updated behavior.<br />
<br />
==Feature Lifespan Example==<br />
<br />
Using the CMF_00001 || CMF_ESCAPE_DEFINITIONS example above let's examine how it would work. In CMake 2.4 definitions had to be escaped by the user which probably does not work on MSVC etc. So in 2.6 we want to start switching over to having CMake handle the escaping. <br />
<br />
* CMake 2.4: old behavior, issue CMF_0001 does not even exist<br />
<br />
* CMake 2.6: issue CMF_0001 is created and set to WARN and version number 2.6. By default old projects will still work but will receive a warning. The issue can be either made QUIET "cmake_feature(SET CMF_0001 QUIET) with no other changes to the CMakeLists file or the issue can be fixed by changing their code and setting it to FIXED "cmake_feature(SET CMF_0001 FIXED). Or they can ignore it and just live with the warnings.<br />
<br />
* CMake 2.8: Nothing changes, stays as a warning<br />
<br />
* CMake 2.10: We change the default value of issue CMF_0001 to REQUIRED. Now if the user's CMakeLists file sets the issue to QUITE or WARN CMake will produce an error indicating that that is no longer an option for feature CMF_0001 and the issue must be fixed or an earlier version of CMake used. But what if the CMakeList file does not specify anything about CMF_0001? In that case we do nothing if the feature is not used. If it is used, we look at the VERSION the CMakeList file was written to. If it was written to CMake 2.6 or later we assume it is fixed. If it is written to an earlier version we assume it is not fixed and report an error.<br />
<br />
* CMake 2.12: We change the default value of issue CMF_0001 to REQUIRED_NO_CHECK. This is the same as required if the CMakeList file specifies anything about CMF_0001. But if it does not, then we produce an error if the CMakeLists file was written to CMake 2.4 or earlier. We do not check to see if they are using the feature at all. That code has been removed. They must have specified that they are using CMake 2.6 or later via cmake_minimum_required(2.6) or cmake_feature(VERSION 2.6) or later.<br />
<br />
==Discussion==<br />
<br />
This solution has the following advantages:<br />
<br />
* All compatibility issues are documented and given unique identifiers<br />
** Documentation can include association with CMake version ranges (when introduced, when REQUIRED, etc.)<br />
* We can be more aggressive about detecting cases without worrying about false positives because it is just a warning<br />
* When generating a warning or error message we can reference the feature id and tell the user what to do<br />
* Projects can be converted to newer CMake features incrementally<br />
* Project authors will be motivated by the warnings to update their code, but it will build for users without extra work<br />
* Code written that does not hit one of these issues will work without any special declarations<br />
** The hello-world example does not need to show version specification<br />
* We have an exit-path to remove support for a compatibility feature eventually<br />
** Make projects rule to FIXED explicitly or via VERSION specification<br />
* Any compatibility bug introduced accidentally and reported by a user can be fixed in CMake by converting it to one of these issues<br />
<br />
==Alternative Names==<br />
<br />
I'm not happy with the current naming. Perhaps the command could be <code>cmake_behavior</code> and <code>QUIET|WARN|ERROR|FIXED</code> should be <code>OLD|WARN|ERROR|NEW</code>:<br />
<br />
cmake_behavior(PUSH)<br />
cmake_behavior(SET CMB_00001 OLD) # request old behavior<br />
cmake_behavior(SET CMB_00001 WARN) # request old behavior with warning<br />
cmake_behavior(SET CMB_00001 ERROR) # request error when case is encountered<br />
cmake_behavior(SET CMB_00001 NEW) # request new behavior<br />
cmake_behavior(VERSION 2.6) # request new behavior as of CMake 2.6<br />
cmake_behavior(POP)<br />
<br />
Or perhaps "<code>cmake_policy</code>"<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP_00001 OLD) # request old policy<br />
cmake_policy(SET CMP_00001 WARN) # request old policy with warning<br />
cmake_policy(SET CMP_00001 ERROR) # request error when case is encountered<br />
cmake_policy(SET CMP_00001 NEW) # request new policy<br />
cmake_policy(VERSION 2.6) # request new policy as of CMake 2.6<br />
cmake_policy(POP)</div>Martinkhttps://public.kitware.com/Wiki/index.php?title=CMake_Policies_Design_Discussion&diff=11731CMake Policies Design Discussion2008-02-26T15:48:49Z<p>Martink: /* Proposed Solution */</p>
<hr />
<div>This page describes a proposal for a formal backwards/forwards compatibility feature.<br />
<br />
=Motivating Examples=<br />
<br />
==The ADD_DEFINITIONS Command==<br />
<br />
Consider code such as<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
which tries to add the option<br />
<br />
-DFOO=\"hello\ world\"<br />
<br />
to the compile command line. The code works in CMake 2.4's <code>Unix Makefiles</code> generator and produces a definition as if<br />
<br />
#define FOO "hello world"<br />
<br />
appeared in the source code. It works only because of the way the makefile generator happens to place the definition string in the command line. It may not work with the VS IDE generators.<br />
In CMake HEAD we provide the <code>COMPILE_DEFINITIONS</code> directory property so that one may write<br />
<br />
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "FOO=\"hello world\"")<br />
<br />
to get the correct behavior on all generators. Since CMake HEAD contains the appropriate escaping support it is desirable to allow the user to write<br />
<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
and get the expected behavior. Unfortunately if we were to start escaping the definitions given to <code>add_definitions</code> we would break compatibility with projects that are already adding their own escapes. In hindsight we should have either supported escapes from the beginning or make the command give an error that the definition value is not supported, but it is too late now.<br />
A similar problem appears in the <code>add_custom_command</code> command where support for properly escaping all arguments was added late. The solution currently used by that command is to require the user to add a <code>VERBATIM</code> argument to the command to get proper escaping. Using that solution for <code>add_definitions</code> would make the user write<br />
<br />
add_definitions(VERBATIM "-DFOO=\"hello world\"")<br />
<br />
just to get CMake to do the right thing. For compatibility CMake would have to implement the wrong behavior by default forever.<br />
<br />
==Missing Link Directories==<br />
<br />
Projects used to be able to write this (wrong) code and it would work by accident:<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>". This code is incorrect <br />
because it asks CMake to link to <code>B</code> but does not provide the proper <br />
linker search path for it. It used to work by accident because the <br />
<code>-L/path/to</code> would get added as part of the implementation of linking to <br />
A. The correct code would be<br />
<br />
link_directories(/path/to)<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so B)<br />
<br />
or even better<br />
<br />
add_executable(myexe myexe.c)<br />
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)<br />
<br />
Currently we provide the <code>CMAKE_OLD_LINK_PATHS</code> variable to allow projects or users to quickly work around the problem. Full compatibility would require us to support thie behavior by default forever. That would allow new projects to be written with the same bug.<br />
<br />
An alternative is to require all libraries to be linked via full path (where target names are expanded automatically). Whenever a non-full-path is given we could produce a warning that tells the user to start using <code>find_library</code> or something like that but then implement the old linker search path computation for compatibility. It is desirable to let projects that have been updated for newer CMake versions tell CMake that they know what they are doing and to not warn or use the compatibility behavior.<br />
<br />
=Proposed Solution=<br />
<br />
We propose the following solution to this problem.<br />
<br />
Each change that introduces a compatibility issue is assigned a new identification number (like CM00001 or something). Then we try to detect cases in user code where it '''might''' be an issue and deal with it. We can maintain in the implementation of CMake a mapping from feature id to a rule to deal with the issue when encountered. The possible means of dealing with such cases are:<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Rule !! Behavior !! Meaning !! Default?<br />
|-<br />
| QUIET || old || Project suppresses the diagnostic || only in special cases<br />
|-<br />
| WARN || old || Emit warning when case is encountered || most cases<br />
|-<br />
| ERROR || none || Emit error when case is encountered || only for cases that can be detected with no false positives<br />
|-<br />
| FIXED || new || Project declares the case has been resolved || never? distant future release after creation of issue?<br />
|-<br />
| REQUIRED || new || Must use the new behavior || future CMake release, compatibility can be dropped but still checked for<br />
|-<br />
| REQUIRED_NO_CHECK || new || Must use the new behavior || future CMake release, compatibility is dropped as well as the code to check for this issue<br />
|}<br />
<br />
Several releases after a compatibility issue has been introduced we can remove implementation of support for the old behavior and set it to "REQUIRED" internally that requires a project to declare the issue FIXED or to be of a CMake version such that we know it would have generated warning. See the feature lifespan example.<br />
<br />
==Proposed CMAKE_FEATURE Command==<br />
<br />
We will introduce a new command for projects to use for setting the rule for each feature.<br />
<br />
The signature<br />
<br />
cmake_feature(SET <feature-id> <QUIET|WARN|ERROR|FIXED>)<br />
<br />
sets the current rule for the feature. It is an error to specify a feature id that does not exist (because it might refer to a feature id introduced in a future version of CMake).<br />
<br />
The signature<br />
<br />
cmake_feature(VERSION <major[.minor[.patch]]>)<br />
<br />
sets the current rules for all features to match the preferred (new) behavior as of a given CMake version and also requires the running CMake to be at least that version. The <code>cmake_minimum_required(VERSION)</code> command can do something similar (but use of new commands versus fixing other issues are distinct cases so the defaults may need to be different).<br />
<br />
The signature<br />
<br />
cmake_feature(PUSH|POP)<br />
<br />
pushes or pops the current feature state on a stack. The stack is automatically pushed/popped when entering a new directory (under <code>add_subdirectory</code> for example). Within a directory the number of PUSH and POP calls must match or it is an error. This signature is useful in a .cmake script meant for inclusion in other projects. It could write<br />
<br />
cmake_feature(PUSH)<br />
cmake_feature(SET CMF_00001 FIXED)<br />
... code using CMF_00001 ...<br />
cmake_feature(POP)<br />
<br />
The command could also provide an alias for each feature id that is more human readable:<br />
<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
<br />
==Examples==<br />
<br />
Let's define a few example feature ids<br />
<br />
{| border="1"<br />
|- bgcolor="#abcdef"<br />
! Id !! Alias !! Description<br />
|-<br />
| CMF_00001 || CMF_ESCAPE_DEFINITIONS || Enable proper escaping of definitions added with ADD_DEFINITIONS<br />
|-<br />
| CMF_00002 || CMF_ESCAPE_CUSTOM_COMMANDS || Enable proper escaping of custom command lines with ADD_CUSTOM_COMMAND, make VERBATIM argument an error<br />
|-<br />
| CMF_00003 || CMF_NO_AUTOMATIC_LINK_PATHS || Disable generation of compatibility -L options on link lines<br />
|}<br />
<br />
The code<br />
<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
can now produce a warning CMF_00001 that CMake does not know whether to escape the definition (only when a non-trivial value is given).<br />
<br />
The project may suppress the warning in their release branch:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS QUIET)<br />
...<br />
add_definitions("-DFOO=\\\"hello\\ world\\\"")<br />
<br />
or fix the code:<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_DEFINITIONS FIXED)<br />
...<br />
add_definitions("-DFOO=\"hello world\"")<br />
<br />
Either way CMake knows exactly how to handle the code and does not need to warn.<br />
<br />
Similarly, the code<br />
<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
may now produce a warning CMF_00002 that CMake does not know whether to escape the command.<br />
The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_ESCAPE_CUSTOM_COMMANDS FIXED)<br />
...<br />
add_custom_command(OUTPUT foo.txt COMMAND mycmd -with -some -arguments -out foo.txt)<br />
<br />
to get rid of the warning and use proper escaping.<br />
<br />
The code<br />
<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
may now produce a warning CMF_00003 that library B may not have the correct link directory specified but then generate -L/path/to anyway. The project may write<br />
<br />
project(FOO)<br />
cmake_feature(SET CMF_NO_AUTOMATIC_LINK_PATHS FIXED)<br />
...<br />
link_directories(/path/to)<br />
target_link_libraries(mytarget /path/to/libA.so B)<br />
<br />
Once the project has fixed all issues related to upgrading to CMake 2.6 it can just write<br />
<br />
project(FOO)<br />
cmake_feature(VERSION 2.6)<br />
<br />
to get all the updated behavior.<br />
<br />
==Feature Lifespan Example==<br />
<br />
Using the CMF_00001 || CMF_ESCAPE_DEFINITIONS example above let's examine how it would work. In CMake 2.4 definitions had to be escaped by the user which probably does not work on MSVC etc. So in 2.6 we want to start switching over to having CMake handle the escaping. <br />
<br />
CMake 2.4: old behavior, issue CMF_0001 does not even exist<br />
<br />
CMake 2.6: issue CMF_0001 is created and set to WARN and version number 2.6. By default old projects will still work but will receive a warning. The issue can be either made QUIET "cmake_feature(SET CMF_0001 QUIET) with no other changes to the CMakeLists file or the issue can be fixed by changing their code and setting it to FIXED "cmake_feature(SET CMF_0001 FIXED). Or they can ignore it and just live with the warnings.<br />
<br />
CMake 2.8: Nothing changes, stays as a warning<br />
<br />
CMake 2.10: We change the default value of issue CMF_0001 to REQUIRED. Now if the user's CMakeLists file sets the issue to QUITE or WARN CMake will produce an error indicating that that is no longer an option for feature CMF_0001 and the issue must be fixed or an earlier version of CMake used. But what if the CMakeList file does not specify anything about CMF_0001? In that case we do nothing if the feature is not used. If it is used, we look at the VERSION the CMakeList file was written to. If it was written to CMake 2.6 or later we assume it is fixed. If it is written to an earlier version we assume it is not fixed and report an error.<br />
<br />
CMake 2.12: We change the default value of issue CMF_0001 to REQUIRED_NO_CHECK. This is the same as required if the CMakeList file specifies anything about CMF_0001. But if it does not, then we produce an error if the CMakeLists file was written to CMake 2.4 or earlier. We do not check to see if they are using the feature at all. That code has been removed. They must have specified that they are using CMake 2.6 or later via cmake_minimum_required(2.6) or cmake_feature(VERSION 2.6) or later.<br />
<br />
==Discussion==<br />
<br />
This solution has the following advantages:<br />
<br />
* All compatibility issues are documented and given unique identifiers<br />
** Documentation can include association with CMake version ranges (when introduced, when REQUIRED, etc.)<br />
* We can be more aggressive about detecting cases without worrying about false positives because it is just a warning<br />
* When generating a warning or error message we can reference the feature id and tell the user what to do<br />
* Projects can be converted to newer CMake features incrementally<br />
* Project authors will be motivated by the warnings to update their code, but it will build for users without extra work<br />
* Code written that does not hit one of these issues will work without any special declarations<br />
** The hello-world example does not need to show version specification<br />
* We have an exit-path to remove support for a compatibility feature eventually<br />
** Make projects rule to FIXED explicitly or via VERSION specification<br />
* Any compatibility bug introduced accidentally and reported by a user can be fixed in CMake by converting it to one of these issues<br />
<br />
==Alternative Names==<br />
<br />
I'm not happy with the current naming. Perhaps the command could be <code>cmake_behavior</code> and <code>QUIET|WARN|ERROR|FIXED</code> should be <code>OLD|WARN|ERROR|NEW</code>:<br />
<br />
cmake_behavior(PUSH)<br />
cmake_behavior(SET CMB_00001 OLD) # request old behavior<br />
cmake_behavior(SET CMB_00001 WARN) # request old behavior with warning<br />
cmake_behavior(SET CMB_00001 ERROR) # request error when case is encountered<br />
cmake_behavior(SET CMB_00001 NEW) # request new behavior<br />
cmake_behavior(VERSION 2.6) # request new behavior as of CMake 2.6<br />
cmake_behavior(POP)<br />
<br />
Or perhaps "<code>cmake_policy</code>"<br />
<br />
cmake_policy(PUSH)<br />
cmake_policy(SET CMP_00001 OLD) # request old policy<br />
cmake_policy(SET CMP_00001 WARN) # request old policy with warning<br />
cmake_policy(SET CMP_00001 ERROR) # request error when case is encountered<br />
cmake_policy(SET CMP_00001 NEW) # request new policy<br />
cmake_policy(VERSION 2.6) # request new policy as of CMake 2.6<br />
cmake_policy(POP)</div>Martink