README.md (6874B)
1 # Star 3D 2 3 Star-3D is a C library that manages *surface geometries* and implements 4 operators to access them efficiently such as uniform sampling, ray 5 tracing or a closest point query. 6 7 The main concept exposed in Star-3D is the *shape*. A shape represents a 8 3D surfacic object such as a *triangular mesh* or a *sphere*. Shape data 9 is user-defined and can be updated at any time. The shapes are then 10 attached to a *scene* where they can be queried. We point out that a 11 scene can be *instantiated* once or several times in a new shape which 12 can be attached to another scene like any other shape. Each instantiated 13 scene has its own position and orientation while its geometry is stored 14 once even if the scene is instantiated multiple times. This feature can 15 thus be used to create an extremely complex environment with a small 16 memory footprint. 17 18 To query scene data, you need to create a *view* of the scene. A view is 19 actually a scene on which accelerating data structures are built to 20 accelerate the aforementioned access operators such as ray tracing. 21 These data structures are constructed from the scene geometry as defined 22 at the time of view creation. A view is thus insensitive to updates of 23 the scene following its creation. This means that multiple views can be 24 used to save different states of the same scene, giving the caller great 25 flexibility in managing scene data. 26 27 ## Requirements 28 29 - C compiler (C99) 30 - POSIX make 31 - pkg-config 32 - [Embree](https://github.com/embree/embree) 33 - [RSys](https://gitlab.com/vaplv/rsys) 34 35 ## Installation 36 37 Edit config.mk as needed, then run: 38 39 make clean install 40 41 ## Release notes 42 43 ### Version 0.10 44 45 - Replace CMake by Makefile as build system. 46 - Update compiler and linker flags to increase the security and 47 robustness of generated binaries. 48 - Provide a pkg-config file to link the library as an external 49 dependency. 50 51 ### Version 0.9 52 53 Upgrading the ray-tracing backend from Embree3 to Embree4 54 55 ### Version 0.8.1 56 57 Fix compilation warnings with GCC 11 58 59 ### Version 0.8 60 61 Update the API of the filtering function: add the range of the ray as 62 input argument. For closest point queries, this range is from 0 to query 63 radius. 64 65 ### Version 0.7.4 66 67 - Fix the barycentric coordinates of the intersection of the ray onto 68 the triangle: the coordinates could lie outside the triangle. 69 - Fix compilation warnings. 70 71 ### Version 0.7.3 72 73 - Fix the `s3d_scene_view_closest_point` function on the scenes 74 containing instantiated meshes: the rotation of the instances was 75 wrongly taken into account. 76 - Speed up the `s3d_scene_view_closest_point` query on instantiated 77 meshes. 78 79 ### Version 0.7.2 80 81 - Fix a precision issue in the `s3d_scene_view_closest_point` function: 82 the returned hit could have invalid barycentric coordinates. 83 84 ### Version 0.7.1 85 86 - Fix an invalid memory read at the setup of the scene view when the 87 `S3D_TRACE` flag was set. The Embree backend assumes that the last 88 vertex position is at least 16 bytes length while its size was only of 89 12 bytes (i.e. 3 single-precision floating-point values). 90 91 ### Version 0.7 92 93 - Add the `s3d_scene_view_closest_point` function. This function 94 retrieves the closest point into the scene to a query position in a 95 radius from ]0, INF]. This closest point is returned as a regular hit 96 which means that the function returns to the caller not only the 97 distance to the query position, but also the geometric primitive onto 98 which the point lies and its location onto this primitive. If no 99 surface lies around the query position in a distance lesser than the 100 one defined by the query radius, the returned hit is invalid which can 101 be checked with the regular `S3D_HIT_NONE` macro. Finally, this 102 function supports the filter functions so that the caller can choose 103 to discard closest hits according to its own criteria. 104 - Add the `s3d_scene_view_create2` function that allows the user to 105 configure the acceleration structure used to partition the scene 106 geometry. The caller can thus control the quality of the structure and 107 thus the compromise between the building time and the query 108 performances. 109 - Improve the performances of the scene bounding box computation. First 110 of all, if the scene view is created with the `S3D_TRACE` flag, 111 Star-3D directly retrieves the scene bounding box from Embree that 112 already computed it to build the acceleration structure. Finally, it 113 internally tries to avoid to recompute the bounding box if the scene 114 was not updated between 2 scene view creations. 115 116 ### Version 0.6.2 117 118 - Fix an issue in `s3d_scene_view_compute_area`: the returned area was 119 wrong when the scene view was created with the `S3D_SAMPLE` flag. 120 121 ### Version 0.6.1 122 123 - Fix an issue in `s3d_scene_view_sample`: the samples were not 124 uniformly distributed if the scene contained meshes and spheres. 125 126 ### Version 0.6 127 128 - Migrate the ray-tracing back-end from Embree2 to Embree3. 129 130 ### Version 0.5.1 131 132 - Fix a compilation issue on VC2017. 133 134 ### Version 0.5 135 136 - Add the support of spherical shapes. A sphere is composed of one 137 primitive that can be sampled and/or ray-traced as any other 138 primitives of the scene. Hit filtering is also fully supported. 139 140 ### Version 0.4.2 141 142 - Update the version of the RSys dependency to 0.6: replace the 143 deprecated `[N]CHECK` macros by the new macro `CHK`. 144 145 ### Version 0.4.1 146 147 - Fix the `s3d_scene_view` consistency when it is created from a scene 148 containing instances: the geometries might be not correctly 149 synchronised and thus could be outdated. 150 151 ### Version 0.4 152 153 - Implement the `s3d_scene_view` API; it replaces the 154 `s3d_scene_<begin|end>_session` functions that were removed. A view 155 registers the state of the scene from which it is created. It is used 156 to retrieve the scene data through ray-tracing, sampling or indexing. 157 Several views can be created on the same scene. 158 - Add the possibility to attach a same shape to several scenes. 159 - Fix a memory overconsumption with instantiated shapes: the 160 instantiated back-end data were copied rather than shared. 161 - Add the `s3d_scene_shapes_count` function that returns the overall 162 number of shapes in the scene. 163 - Add the `s3d_instance_set_transform` and `s3d_instance_transform` 164 functions that sets or gets the transformation matrix of the instance, 165 respectively. 166 - Add the `s3d_primitive_get_transform` function that gets the 167 transformation matrix of a primitive. 168 - Add the `s3d_primitive_has_attrib` function that returns if a 169 primitive has a specific attribute or not. 170 - Add the `s3d_triangle_get_vertex_attrib` function that retrieves the 171 vertex attributes of a triangular primitive. 172 173 ## License 174 175 Copyright (C) 2015-2023 |Méso|Star> (contact@meso-star.com) 176 177 Star-3D is free software released under GPL v3+ license: GNU GPL version 178 3 or later. You are welcome to redistribute it under certain conditions; 179 refer to the COPYING file for details.