From 3f42642d2431eefae01e87b497c9a720d93f34e3 Mon Sep 17 00:00:00 2001 From: Robert Maynard Date: Fri, 7 Jul 2017 10:19:22 -0400 Subject: [PATCH] Use Markdown readme as mainpage for doxygen. --- CMake/doxyfile.in | 6 +- README.md | 192 +++++++++++++++++++++++----------------------- 2 files changed, 102 insertions(+), 96 deletions(-) diff --git a/CMake/doxyfile.in b/CMake/doxyfile.in index ebf88e7eb..19c994c47 100644 --- a/CMake/doxyfile.in +++ b/CMake/doxyfile.in @@ -138,7 +138,11 @@ WARN_LOGFILE = # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = @VTKm_SOURCE_DIR@/vtkm +INPUT = @VTKm_SOURCE_DIR@/README.md +INPUT += @VTKm_SOURCE_DIR@/docs/CodingConventions.md +INPUT += @VTKm_SOURCE_DIR@/vtkm + +USE_MDFILE_AS_MAINPAGE = README.md FILE_PATTERNS = *.cxx *.h *.cu diff --git a/README.md b/README.md index 0b7701318..3542db315 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,20 @@ ## VTK-m ## -VTK-m is a toolkit of scientific visualization algorithms for emerging processor architectures. VTK-msupports the fine-grained concurrency for data analysis and visualization algorithms required to drive extreme scale computing by providing abstract models for data and execution that can be applied to a variety of algorithms across many different processor architectures. +VTK-m is a toolkit of scientific visualization algorithms for emerging processor +architectures. VTK-m supports the fine-grained concurrency for data analysis and +visualization algorithms required to drive extreme scale computing by providing +abstract models for data and execution that can be applied to a variety of +algorithms across many different processor architectures. You can find out more about the design of VTK-m on our [wiki][] -Dependencies -============ - -VTK-m Requires: - -+ C++11 Compiler. VTK-m has been confirmed to work with the following - + GCC 4.8+ - + Clang 3.3+ - + XCode 5.0+ - + MSVC 2013+ -+ [CMake 3.3](http://www.cmake.org/download/) - - -Optional dependencies are: - -+ CUDA Device Adapter - + [Cuda Toolkit 7+](https://developer.nvidia.com/cuda-toolkit) -+ TBB Device Adapter - + [TBB](https://www.threadingbuildingblocks.org/) -+ Rendering Module - + The rendering module requires that you have a extension binding library and one rendering library. A windowing library is not needed expect for some optional tests. - + Extension Binding - + [GLEW](http://glew.sourceforge.net/) - + Rendering Canvas - + OpenGL Driver (See your GPU/iGPU vendor) - + EGL (See your GPU/iGPU vendor) - + [OSMesa](https://www.mesa3d.org/osmesa.html) - + Windowing/Contexts - + EGL (See your GPU/iGPU vendor) - + [GLFW](http://www.glfw.org/) - + [GLUT](http://freeglut.sourceforge.net/) - - - -Building -======== - -VTK-m supports all majors platforms ( Windows, Linux, OSX ), and uses CMake -to generate all the build rules for the project. - -``` -$ git clone https://gitlab.kitware.com/vtk/vtk-m.git -$ mkdir vtkm-build -$ cd vtkm-build -$ cmake-gui ../vtk-m -$ make -j -$ make test -``` - -The VTK-m CMake configuration supports several options, including what specific -device adapters ( e.g. CUDA, TBB ) that you wish to enable. Here are some -relevant options - -| Variable | Description | -|-----------------------------|-----------------------------| -| BUILD_SHARED_LIBS | Enabled by default. Build all VTK-m libraries as shared libraries. | -| CMAKE_BUILD_TYPE | This statically specifies what build type (configuration) will be built in this build tree. Possible values are empty, Debug, Release, RelWithDebInfo and MinSizeRel. This variable is only meaningful to single-configuration generators (such as make and Ninja). | -| CMAKE_INSTALL_PREFIX | Directory to install VTK-m into. | -| VTKm_ENABLE_EXAMPLES | Disabled by default. Turn on building of simple examples of using VTK-m. | -| VTKm_ENABLE_BENCHMARKS | Disabled by default. Turn on additional timing tests. | -| VTKm_ENABLE_CUDA | Disabled by default. Enable CUDA backend. | -| VTKm_CUDA_Architecture | Defaults to native. Specify what GPU architecture(s) to build CUDA code for, options include native, fermi, kepler, maxwell, and pascal. | -| VTKm_ENABLE_TBB | Disabled by default. Enable Intel Threading Building Blocks backend. | -| VTKm_ENABLE_TESTING | Enabled by default. Turn on header, unit, worklet, and filter tests. | -| VTKm_ENABLE_RENDERING | Enabled by default. Turn on the rendering module. | -| VTKm_USE_64BIT_IDS | Enabled by default. This is the size of integers used to index arrays, points, cells, etc. Use 64 bit precision when on, 32 bit precision when off. | -| VTKm_USE_DOUBLE_PRECISION | Disabled by default. Precision to use in floating point numbers when no other precision can be inferred. Use 64 bit precision when on, 32 bit precision when off. | - -Learning -======== - -VTK-m offers numerous different ways to learn how to use the provided components. -If you are interested in a high level overview of VTK-m a good place to start -is with the IEEE Vis talk ["VTK-m: Accelerating the Visualization Toolkit for Massively Threaded Architectures"](http://m.vtk.org/images/2/29/VTKmVis2016.pptx) or the older and more technical -presentation -["VTK-m Overview for Intel Design Review"](http://m.vtk.org/images/a/a4/VTKmIntelMeet.pptx). - -If you are interested in learning how to use the existing VTK-m codebase, -or how to integrate into your own project, we recommend reading "Part 1: Getting Started" -and "Part 2: Using VTK-m" of the [VTK-m Users Guide][]. - -If you want to contribute to VTK-m we recommend reading the following sections -of the [VTK-m Users Guide][]. - -+ "Part 2: Using VTK-m" - - Covers the core fundamental components of VTK-m including data model, worklets, and filters. -- "Part 3: Developing with VTK-m" - - Covers how to develop new worklets and filters. -- "Part 4: Advanced Development" - - Covers topics such as new worklet tags, opengl interop and custom device adapters . - - - Example ======= -The VTK-m source distribution includes a number of examples. The goal of the VTK-m examples is to illustrate specific VTK-m concepts in a consistent and simple format. However, these examples only cover a small part of the capabilities of VTK-m. +The VTK-m source distribution includes a number of examples. The goal of the +VTK-m examples is to illustrate specific VTK-m concepts in a consistent and +simple format. However, these examples only cover a small part of the +capabilities of VTK-m. Below is a simple example of using VTK-m to load a VTK image file, run the Marching Cubes algorithm on it, and render the results to an image: @@ -156,6 +70,28 @@ view.Paint(); view.SaveAs("demo_output.pnm"); ``` +Learning +======== + +VTK-m offers numerous different ways to learn how to use the provided components. +If you are interested in a high level overview of VTK-m a good place to start +is with the IEEE Vis talk ["VTK-m: Accelerating the Visualization Toolkit for Massively Threaded Architectures"](http://m.vtk.org/images/2/29/VTKmVis2016.pptx) or the older and more technical presentation +["VTK-m Overview for Intel Design Review"](http://m.vtk.org/images/a/a4/VTKmIntelMeet.pptx). + +If you are interested in learning how to use the existing VTK-m codebase, +or how to integrate into your own project, we recommend reading "Part 1: Getting Started" +and "Part 2: Using VTK-m" of the [VTK-m Users Guide][]. + +If you want to contribute to VTK-m we recommend reading the following sections +of the [VTK-m Users Guide][]. + ++ "Part 2: Using VTK-m" + - Covers the core fundamental components of VTK-m including data model, worklets, and filters. +- "Part 3: Developing with VTK-m" + - Covers how to develop new worklets and filters. +- "Part 4: Advanced Development" + - Covers topics such as new worklet tags, opengl interop and custom device adapters . + Contributing ============ @@ -168,7 +104,73 @@ There are many ways to contribute to [VTK-m][], with varying levels of effort. a Pull Request. ++ Submit an Issue or Pull Request for the [VTK-m User's Guide](http://m.vtk.org/images/c/c8/VTKmUsersGuide.pdf) +Dependencies +============ +VTK-m Requires: + ++ C++11 Compiler. VTK-m has been confirmed to work with the following + + GCC 4.8+ + + Clang 3.3+ + + XCode 5.0+ + + MSVC 2013+ ++ [CMake 3.3](http://www.cmake.org/download/) + + +Optional dependencies are: + ++ CUDA Device Adapter + + [Cuda Toolkit 7+](https://developer.nvidia.com/cuda-toolkit) ++ TBB Device Adapter + + [TBB](https://www.threadingbuildingblocks.org/) ++ Rendering Module + + The rendering module requires that you have a extension binding library + and one rendering library. A windowing library is not needed expect + for some optional tests. + + Extension Binding + + [GLEW](http://glew.sourceforge.net/) + + Rendering Canvas + + OpenGL Driver (See your GPU/iGPU vendor) + + EGL (See your GPU/iGPU vendor) + + [OSMesa](https://www.mesa3d.org/osmesa.html) + + Windowing/Contexts + + EGL (See your GPU/iGPU vendor) + + [GLFW](http://www.glfw.org/) + + [GLUT](http://freeglut.sourceforge.net/) + +Building +======== + +VTK-m supports all majors platforms ( Windows, Linux, OSX ), and uses CMake +to generate all the build rules for the project. + +``` +$ git clone https://gitlab.kitware.com/vtk/vtk-m.git +$ mkdir vtkm-build +$ cd vtkm-build +$ cmake-gui ../vtk-m +$ make -j +$ make test +``` + +The VTK-m CMake configuration supports several options, including what specific +device adapters ( e.g. CUDA, TBB ) that you wish to enable. Here are some +relevant options + +| Variable | Description | +|-----------------------------|-----------------------------| +| BUILD_SHARED_LIBS | Enabled by default. Build all VTK-m libraries as shared libraries. | +| CMAKE_BUILD_TYPE | This statically specifies what build type (configuration) will be built in this build tree. Possible values are empty, Debug, Release, RelWithDebInfo and MinSizeRel. This variable is only meaningful to single-configuration generators (such as make and Ninja). | +| CMAKE_INSTALL_PREFIX | Directory to install VTK-m into. | +| VTKm_ENABLE_EXAMPLES | Disabled by default. Turn on building of simple examples of using VTK-m. | +| VTKm_ENABLE_BENCHMARKS | Disabled by default. Turn on additional timing tests. | +| VTKm_ENABLE_CUDA | Disabled by default. Enable CUDA backend. | +| VTKm_CUDA_Architecture | Defaults to native. Specify what GPU architecture(s) to build CUDA code for, options include native, fermi, kepler, maxwell, and pascal. | +| VTKm_ENABLE_TBB | Disabled by default. Enable Intel Threading Building Blocks backend. | +| VTKm_ENABLE_TESTING | Enabled by default. Turn on header, unit, worklet, and filter tests. | +| VTKm_ENABLE_RENDERING | Enabled by default. Turn on the rendering module. | +| VTKm_USE_64BIT_IDS | Enabled by default. This is the size of integers used to index arrays, points, cells, etc. Use 64 bit precision when on, 32 bit precision when off. | +| VTKm_USE_DOUBLE_PRECISION | Disabled by default. Precision to use in floating point numbers when no other precision can be inferred. Use 64 bit precision when on, 32 bit precision when off. | License =======