README.md (7087B)
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.1 44 45 - Fix an issue related to deleting a scene view. 46 The process could crash when the same shape was repeatedly detected as 47 being detached from the scene for which the view was created. 48 49 ### Version 0.10 50 51 - Replace CMake by Makefile as build system. 52 - Update compiler and linker flags to increase the security and 53 robustness of generated binaries. 54 - Provide a pkg-config file to link the library as an external 55 dependency. 56 57 ### Version 0.9 58 59 Upgrading the ray-tracing backend from Embree3 to Embree4 60 61 ### Version 0.8.1 62 63 Fix compilation warnings with GCC 11 64 65 ### Version 0.8 66 67 Update the API of the filtering function: add the range of the ray as 68 input argument. For closest point queries, this range is from 0 to query 69 radius. 70 71 ### Version 0.7.4 72 73 - Fix the barycentric coordinates of the intersection of the ray onto 74 the triangle: the coordinates could lie outside the triangle. 75 - Fix compilation warnings. 76 77 ### Version 0.7.3 78 79 - Fix the `s3d_scene_view_closest_point` function on the scenes 80 containing instantiated meshes: the rotation of the instances was 81 wrongly taken into account. 82 - Speed up the `s3d_scene_view_closest_point` query on instantiated 83 meshes. 84 85 ### Version 0.7.2 86 87 - Fix a precision issue in the `s3d_scene_view_closest_point` function: 88 the returned hit could have invalid barycentric coordinates. 89 90 ### Version 0.7.1 91 92 - Fix an invalid memory read at the setup of the scene view when the 93 `S3D_TRACE` flag was set. The Embree backend assumes that the last 94 vertex position is at least 16 bytes length while its size was only of 95 12 bytes (i.e. 3 single-precision floating-point values). 96 97 ### Version 0.7 98 99 - Add the `s3d_scene_view_closest_point` function. This function 100 retrieves the closest point into the scene to a query position in a 101 radius from ]0, INF]. This closest point is returned as a regular hit 102 which means that the function returns to the caller not only the 103 distance to the query position, but also the geometric primitive onto 104 which the point lies and its location onto this primitive. If no 105 surface lies around the query position in a distance lesser than the 106 one defined by the query radius, the returned hit is invalid which can 107 be checked with the regular `S3D_HIT_NONE` macro. Finally, this 108 function supports the filter functions so that the caller can choose 109 to discard closest hits according to its own criteria. 110 - Add the `s3d_scene_view_create2` function that allows the user to 111 configure the acceleration structure used to partition the scene 112 geometry. The caller can thus control the quality of the structure and 113 thus the compromise between the building time and the query 114 performances. 115 - Improve the performances of the scene bounding box computation. First 116 of all, if the scene view is created with the `S3D_TRACE` flag, 117 Star-3D directly retrieves the scene bounding box from Embree that 118 already computed it to build the acceleration structure. Finally, it 119 internally tries to avoid to recompute the bounding box if the scene 120 was not updated between 2 scene view creations. 121 122 ### Version 0.6.2 123 124 - Fix an issue in `s3d_scene_view_compute_area`: the returned area was 125 wrong when the scene view was created with the `S3D_SAMPLE` flag. 126 127 ### Version 0.6.1 128 129 - Fix an issue in `s3d_scene_view_sample`: the samples were not 130 uniformly distributed if the scene contained meshes and spheres. 131 132 ### Version 0.6 133 134 - Migrate the ray-tracing back-end from Embree2 to Embree3. 135 136 ### Version 0.5.1 137 138 - Fix a compilation issue on VC2017. 139 140 ### Version 0.5 141 142 - Add the support of spherical shapes. A sphere is composed of one 143 primitive that can be sampled and/or ray-traced as any other 144 primitives of the scene. Hit filtering is also fully supported. 145 146 ### Version 0.4.2 147 148 - Update the version of the RSys dependency to 0.6: replace the 149 deprecated `[N]CHECK` macros by the new macro `CHK`. 150 151 ### Version 0.4.1 152 153 - Fix the `s3d_scene_view` consistency when it is created from a scene 154 containing instances: the geometries might be not correctly 155 synchronised and thus could be outdated. 156 157 ### Version 0.4 158 159 - Implement the `s3d_scene_view` API; it replaces the 160 `s3d_scene_<begin|end>_session` functions that were removed. A view 161 registers the state of the scene from which it is created. It is used 162 to retrieve the scene data through ray-tracing, sampling or indexing. 163 Several views can be created on the same scene. 164 - Add the possibility to attach a same shape to several scenes. 165 - Fix a memory overconsumption with instantiated shapes: the 166 instantiated back-end data were copied rather than shared. 167 - Add the `s3d_scene_shapes_count` function that returns the overall 168 number of shapes in the scene. 169 - Add the `s3d_instance_set_transform` and `s3d_instance_transform` 170 functions that sets or gets the transformation matrix of the instance, 171 respectively. 172 - Add the `s3d_primitive_get_transform` function that gets the 173 transformation matrix of a primitive. 174 - Add the `s3d_primitive_has_attrib` function that returns if a 175 primitive has a specific attribute or not. 176 - Add the `s3d_triangle_get_vertex_attrib` function that retrieves the 177 vertex attributes of a triangular primitive. 178 179 ## License 180 181 Copyright (C) 2015-2023, 2026 |Méso|Star> (contact@meso-star.com) 182 183 Star-3D is free software released under GPL v3+ license: GNU GPL version 184 3 or later. You are welcome to redistribute it under certain conditions; 185 refer to the COPYING file for details.