commit 16b9b763da14af674b8b58c4377ca769bab31b27
parent 5fbeb5c6df8797aa26d9d03904862bcf52a8be9c
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 15 Feb 2016 14:38:48 +0100
Update the README file
Rewrite some parts of the overview section. Add a quick start section
that explains what is actually installed and how to use the CMake
package.
Diffstat:
| M | README.md | | | 78 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------- |
1 file changed, 62 insertions(+), 16 deletions(-)
diff --git a/README.md b/README.md
@@ -3,24 +3,25 @@
## Overview
Star-3D is a C/C++ library whose purpose is to manage a virtual environment
-composed of 3D triangular meshes. The resulting virtual world can then be
+composed of triangular meshes. The resulting virtual world can then be
ray-traced and sampled, providing an efficient way to deal with geometric data
of arbitrary 3D contents. In addition of purely geometric data, user defined
-per vertex attributes can be defined. This provides a simple way to handle 3D
-attributes that spatially varies over the geometry surface. The target user of
-Star-3D are software engineers that have to deal with complex 3D environments
-as numerical simulation engineers, researchers in complex systems or graphics
-programmers. Its backend relies on the [Embree](https://embree.github.io)
-library to ensure high ray-tracing performances on a wide range of x86
-architectures.
+per vertex data can be setup, allowing the definition of attributes that
+spatially vary over the geometry surface. To ensure high ray-tracing
+efficiency, the Star-3D back-end heavily relies on the Intel
+[Embree](https://embree.github.io) library that provides several ray-tracing
+kernels optimized for a wide range of data workloads. The target users of
+Star-3D are thus programmers that have to efficiently deal with complex 3D
+environment as numerical simulation engineers, researchers in complex systems
+or graphics programmers.
The main concept exposed by the Star-3D C API are *shapes*. A *shape*
represents a 3D object whose data is defined by the user and can be updated at
any time. A 3D environment is built by attaching one or several *shapes* to a
*scene*. To access the *scene* data through sampling, ray-tracing or indexing,
one have to enable a *scene session* that commits the current *scene* geometry
-as the geometry to use. We point out that a *scene* can also be instantiated
-into one or several *shapes*, each with its own attributes (e.g. position).
+as the geometry to use. A *scene* can also be instantiated into one or several
+*shapes*, each with its own attributes (e.g. position, orientation, etc.).
Since the *scene* geometry is stored once even though it is instantiated
several times, this feature can be used to create extremely complex environment
with a low memory footprint.
@@ -51,20 +52,65 @@ First ensure that CMake and a C/C++ compiler is installed on your system. Then
install the [RCMake](https://gitlab.com/vaplv/rcmake.git) package as well as
the [RSys](https://gitlab.com/vaplv/rsys.git) and
[Embree](https://embree.github.io) libraries. Finally generate the project from
-the `cmake/CMakeLists.txt` file by appending to the
-`CMAKE_PREFIX_PATH` variable the `<RCMAKE_INSTALL_DIR>/lib/cmake`,
-`<RSYS_INSTALL_DIR>` and `<EMBREE_INSTALL_DIR>` directories, where
-`<RCMAKE_INSTALL_DIR>`, `<RSYS_INSTALL_DIR>` and `<EMBREE_INSTALL_DIR`> are the
+the `cmake/CMakeLists.txt` file by appending to the `CMAKE_PREFIX_PATH`
+variable the `<RCMAKE_DIR>/lib/cmake`, `<RSYS_DIR>` and `<EMBREE_DIR>`
+directories, where `<RCMAKE_DIR>`, `<RSYS_DIR>` and `<EMBREE_DIR`> are the
install directories of the RCMake package, the RSys and the Embree libraries,
respectively. The resulting project can be edited, built, tested and installed
-as any CMake project.
+as any CMake project (Refer to the [CMake
+documentation](https://cmake.org/documentation) for further informations on
+CMake).
Example on a GNU/Linux system:
~ $ git clone https://gitlab.com/meso-star/star-3d.git
~ $ mkdir star-3d/build && cd star-3d/build
- ~/star-3d/build $ cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH="<RCMAKE_INSTALL_DIR>/lib/cmake;<RSYS_INSTALL_DIR>;<EMBREE_INSTALL_DIR>" ../cmake
+ ~/star-3d/build $ cmake -G "Unix Makefiles" \
+ > -DCMAKE_PREFIX_PATH="<RCMAKE_DIR>/lib/cmake;<RSYS_DIR>;<EMBREE_DIR>" \
+ > -DCMAKE_INSTALL_PREFIX=<STAR3D_INSTALL_DIR> \
+ > ../cmake
~/star-3d/build $ make && make test
+ ~/star-3d/build $ make install
+
+with `<STAR3D_INSTALL_DIR>` the directory in which Star-3D is going to be
+installed.
+
+## Quick Start
+
+Once installed, the Star-3D library and its associated headers are deployed,
+providing the whole environment required to develop C/C++ applications with
+Star-3D. The `<STAR3D_INSTALL_DIR>/include/star/s3d.h` header defines the
+Star-3D Application Programming Interface (API). Refer to this
+[file](https://gitlab.com/meso-star/star-3d/blob/master/src/s3d.h) for the API
+reference documentation.
+
+
+A Star-3D [CMake
+package](https://cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html) is
+also installed to facilitate the use of Star-3D in projects relying on the
+CMake build system. For instance, the following `CMakeLists.txt` file uses the
+Star-3D package to build an executable relying on the Star-3D library.
+
+ project(my_project C)
+
+ # Use the Star-3D CMake package
+ find_package(Star3D REQUIRED)
+
+ # Define the program to build
+ add_executable(my_program main.c)
+
+ # Link the program against Star-3D
+ target_link_libraries(my_program Star3D)
+
+This `CMakeLists.txt` is then used to generate the target project as, for
+instance, on a GNU/Linux system:
+
+ cmake -G "Unix Makefiles" \
+ > -DCMAKE_PREFIX_PATH="<STAR3D_INSTALL_DIR>/lib/cmake;<STAR3D_INSTALL_DIR>" \
+ > <MY_PROJECT_DIR>
+
+with `<STAR3D_INSTALL_DIR>` the install directory of Star-3D and
+`<MY_PROJECT_DIR>` the location of the `CMakeLists.txt` file.
## License
