Free Electron
SurfaceI.h
Go to the documentation of this file.
1 /* Copyright (C) 2003-2021 Free Electron Organization
2  Any use of this software requires a license. If a valid license
3  was not distributed with this file, visit freeelectron.org. */
4 
5 /** @file */
6 
7 #ifndef __surface_SurfaceI_h__
8 #define __surface_SurfaceI_h__
9 
10 namespace fe
11 {
12 namespace ext
13 {
14 
15 /**************************************************************************//**
16  @brief Spatial boundary
17 
18  @ingroup surface
19 *//***************************************************************************/
20 class FE_DL_EXPORT SurfaceI:
21  virtual public Component,
22  public CastableAs<SurfaceI>
23 {
24  public:
25  enum SampleMethod
26  {
27  e_flat,
28  e_linear,
29  e_pointNormal,
30  e_spline
31  };
32 
33  enum Containment
34  {
35  e_unknown,
36  e_inside,
37  e_outside
38  };
39 
40  enum Accuracy
41  {
42  e_sphere,
43  e_triangle
44  };
45 
46  enum Triangulation
47  {
48  e_existingPoints,
49  e_balanced
50  };
51 
52  enum Restrictions
53  {
54  e_unrestricted= 0x0,
55  e_excludeCurves= 0x1,
56  e_excludePolygons= 0x2,
57  };
58 
59  /// @brief results of a surface intersection
60  class FE_DL_EXPORT ImpactI:
61  virtual public Component,
62  public CastableAs<ImpactI>
63  {
64  public:
65  virtual SpatialVector origin(void) const =0;
66 
67  virtual SpatialVector direction(void) const =0;
68 
69  virtual Real distance(void) const =0;
70 
71  virtual SpatialVector intersection(void) =0;
72 
73  virtual SpatialVector normal(void) =0;
74 
75  /// @brief Internal search index
76  virtual I32 face(void) =0;
77 
78  /** @brief Barycentric element index
79 
80  Use this for barycentric sampling.
81  For surfaces converted into triangles,
82  this is simply that index.
83  For curves, this is really
84  the curve index. */
85  virtual I32 triangleIndex(void) =0;
86 
87  /** @brief Source's atomic index
88 
89  This is an index specific to where
90  the pickable element came from.
91  One index may be for a free triangle,
92  a pair of triangles from a quad,
93  a pure quadric, a full NURBS patch,
94  a whole curve, or whatever arbitrary
95  collective was determined relevant by
96  the system it came from. */
97  virtual I32 primitiveIndex(void) =0;
98 
99  /** @brief numerical enumeration
100  of the named partitions */
101  virtual I32 partitionIndex(void) =0;
102 
103  /** @brief Position within a triangle or curve
104 
105  For triangluar representations,
106  this is the barycentric coordinate.
107  For curves, the first vector element
108  is the unit distance along the curve. */
109  virtual SpatialBary barycenter(void) =0;
110  virtual Vector2 uv(void) =0;
111  virtual SpatialVector du(void) =0;
112  virtual SpatialVector dv(void) =0;
113 
114  /// TEMP HACK for xMechanics test
115  /// TODO Material independent from surface
116  virtual Color diffuse(void) const =0;
117  virtual void setDiffuse(Color a_diffuse) =0;
118  };
119 
120  /// @brief calculate surface distances
121  class FE_DL_EXPORT GaugeI: virtual public Counted
122  {
123  public:
124  virtual void pick(SpatialVector a_source,
125  Real a_maxDistance) =0;
126  virtual Real distanceTo(SpatialVector a_target) =0;
127  };
128 
129  /// @brief associate with model data
130 virtual void bind(Instance a_instance) =0;
131 
132 virtual void setSampleMethod(SampleMethod a_sampleMethod) =0;
133 
134 virtual void setNodeName(String a_nodeName) =0;
135 virtual String nodeName(void) const =0;
136 
137 virtual void setRestrictions(Restrictions
138  a_restrictions) =0;
139 virtual Restrictions restrictions(void) const =0;
140 
141  /** @brief Set limitation of surface improvement,
142  such as subdivision
143 
144  Refinement may be fixed or adaptive
145  and is not necessarily uniformly applied.
146 
147  Some surfaces may ignore this setting.*/
148 virtual void setRefinement(U32 a_refinement) =0;
149 
150  /** @brief Set what primitive to search down to
151 
152  Using sphere accuracy will only resolve to
153  the lowest bounding sphere. */
154 virtual void setAccuracy(Accuracy a_accuracy) =0;
155 
156  /** @brief Set whether this surface may be searched
157 
158  Turning this off may allow some
159  implementations to make optimization.
160 
161  An implemention is permitted to remain
162  searchable regardless. */
163 virtual void setSearchable(BWORD a_searchable) =0;
164 
165  /** @brief Set component to use for searching
166 
167  This is presumed to be an implementation
168  of SpatialTreeI.
169  Leave blank for default. */
170 virtual void setSearch(String a_searchName) =0;
171 
172  /** @brief Set how 4+ vertex polygons break down
173 
174  Using balanced triangulation may add new
175  points that did not already exist
176  on the mesh.
177 
178  Some implementations may drop
179  5+ vertex polygons. */
180 virtual void setTriangulation(Triangulation a_triangulation) =0;
181 
182  /** @brief Number of barycentric elements
183 
184  Use this for barycentric sampling.
185  For surfaces converted into triangles,
186  this is the number of triangle.
187  For curves, this is really the curve count.
188  If unknown, an implementation may return -1. */
189 virtual I32 triangleCount(void) =0;
190 
191  /// @name Return the bounding center
192  ///@{
193 virtual SpatialVector center(void) =0;
194 virtual SpatialVector center(void) const =0;
195  ///@}
196 
197  /// @name Return the bounding radius
198  ///@{
199 virtual Real radius(void) =0;
200 virtual Real radius(void) const =0;
201  ///@}
202 
203  /// @brief Return the diffuse color
204 virtual Color diffuse(void) const =0;
205 
206  /** @name Sample local transform on surface
207 
208  The notion of u and v may have limited sense
209  on some surface types. The full domain of
210  u and v may not reach the full range of
211  some surfaces.
212 
213  An implemention is permitted clamp u or v to
214  the range 0 to 1, but may choose to extrapolate
215  in one or both axes.
216 
217  The const version does not permit caching. */
218  ///@{
219 virtual SpatialTransform sample(Vector2 a_uv) =0;
220 virtual SpatialTransform sample(Vector2 a_uv) const =0;
221  ///@}
222 
223  /** @name Sample local transform on a surface face
224 
225  Surfaces that don't have faces may simply
226  return identity.
227 
228  An implemention is permitted clamp the
229  barycentric coordinates to the range 0 to 1,
230  but may choose to extrapolate instead.
231 
232  The const version does not permit caching. */
233  ///@{
234 virtual SpatialTransform sample(I32 a_triangleIndex,
235  SpatialBary a_barycenter) =0;
236 virtual SpatialTransform sample(I32 a_triangleIndex,
237  SpatialBary a_barycenter) const =0;
238 virtual SpatialTransform sample(I32 a_triangleIndex,SpatialBary a_barycenter,
239  SpatialVector a_tangent) const =0;
240  ///@}
241 
242  /** @name Sample surface face as ImpactI
243 
244  This method is similar to sample(),
245  but populates an ImpactI.
246  Not all value may be populated.
247 
248  The const version does not permit caching. */
249  ///@{
250 virtual sp<ImpactI> sampleImpact(I32 a_triangleIndex,
251  SpatialBary a_barycenter) =0;
252 virtual sp<ImpactI> sampleImpact(I32 a_triangleIndex,
253  SpatialBary a_barycenter) const =0;
254 virtual sp<ImpactI> sampleImpact(I32 a_triangleIndex,
255  SpatialBary a_barycenter,
256  SpatialVector a_tangent) const =0;
257  ///@}
258 
259  /** @name Sample location on surface
260 
261  An implemention may just use the translation
262  from the result of sample(), but is encouraged
263  to provide a more efficient limited evaluation,
264  if reasonable.
265 
266  The const version does not permit caching. */
267  ///@{
268 virtual SpatialVector samplePoint(const SpatialTransform& a_transform,
269  Vector2 a_uv) =0;
270 virtual SpatialVector samplePoint(Vector2 a_uv) =0;
271 virtual SpatialVector samplePoint(const SpatialTransform& a_transform,
272  Vector2 a_uv) const =0;
273 virtual SpatialVector samplePoint(Vector2 a_uv) const =0;
274  ///@}
275 
276  /** @name Sample direction from surface
277 
278  An implemention may just use the up vector
279  from the result of sample(), but is encouraged
280  to provide a more efficient limited evaluation,
281  if reasonable.
282 
283  The const version does not permit caching. */
284  ///@{
285 virtual SpatialVector sampleNormal(const SpatialTransform& a_transform,
286  Vector2 a_uv) =0;
287 virtual SpatialVector sampleNormal(Vector2 a_uv) =0;
288 virtual SpatialVector sampleNormal(const SpatialTransform& a_transform,
289  Vector2 a_uv) const =0;
290 virtual SpatialVector sampleNormal(Vector2 a_uv) const =0;
291  ///@}
292 
293  /** @name Build data required for searching
294 
295  This may need to be called at least once
296  before using a const version of nearestPoint
297  or rayImpact. The non-const versions will
298  call it automatically. */
299  ///@{
300 virtual void prepareForSample(void) =0;
301 virtual void prepareForSearch(void) =0;
302 virtual void prepareForUVSearch(void) =0;
303  ///@}
304 
305 virtual Containment containment(const SpatialVector& a_origin) =0;
306 virtual Containment containment(
307  const SpatialVector& a_origin) const =0;
308 
309  /** @name Find the closest point(s) on the surface \
310  from given point
311 
312  Surfaces are not required to support
313  point searches.
314  Any surface is allowed to return a NULL ImpactI.
315 
316  const versions do not permit caching. */
317  ///@{
318 virtual sp<ImpactI> nearestPoint(const SpatialTransform& a_transform,
319  const SpatialVector& a_point,
320  Real a_maxDistance) =0;
321 virtual sp<ImpactI> nearestPoint(const SpatialTransform& a_transform,
322  const SpatialVector& a_point,
323  Real a_maxDistance) const =0;
324 
325 virtual sp<ImpactI> nearestPoint(const SpatialVector& a_point,
326  Real a_maxDistance,BWORD a_anyHit) =0;
327 virtual sp<ImpactI> nearestPoint(const SpatialVector& a_point,
328  Real a_maxDistance,
329  BWORD a_anyHit) const =0;
330 
331 virtual sp<ImpactI> nearestPoint(const SpatialVector& a_point,
332  Real a_maxDistance) =0;
333 virtual sp<ImpactI> nearestPoint(const SpatialVector& a_point,
334  Real a_maxDistance) const =0;
335 
336 virtual sp<ImpactI> nearestPoint(const SpatialVector& a_point) =0;
337 virtual sp<ImpactI> nearestPoint(
338  const SpatialVector& a_point) const =0;
339 
340 virtual sp<ImpactI> nearestPoint(const Vector2& a_uv) =0;
341 virtual sp<ImpactI> nearestPoint(const Vector2& a_uv)const =0;
342 
343 virtual Array< sp<SurfaceI::ImpactI> >
344  nearestPoints(const Vector2& a_uv,
345  Real a_maxDistance,U32 a_hitLimit) =0;
346 virtual Array< sp<SurfaceI::ImpactI> >
347  nearestPoints(const Vector2& a_uv,
348  Real a_maxDistance,
349  U32 a_hitLimit) const =0;
350 
351 virtual Array< sp<SurfaceI::ImpactI> >
352  nearestPoints(const SpatialVector& a_origin,
353  Real a_maxDistance,U32 a_hitLimit) =0;
354 virtual Array< sp<SurfaceI::ImpactI> >
355  nearestPoints(const SpatialVector& a_origin,
356  Real a_maxDistance,
357  U32 a_hitLimit) const =0;
358 
359 virtual Array< sp<SurfaceI::ImpactI> >
360  nearestPoints(const SpatialVector& a_origin,
361  Real a_maxDistance,U32 a_hitLimit,
362  sp<PartitionI> a_spPartition) =0;
363 virtual Array< sp<SurfaceI::ImpactI> >
364  nearestPoints(const SpatialVector& a_origin,
365  Real a_maxDistance,U32 a_hitLimit,
366  sp<PartitionI> a_spPartition) const =0;
367  ///@}
368 
369  /** @name Trace distance(s) to surface in given \
370  direction from the originating point
371 
372  Surfaces are not required to support
373  ray casting.
374  Any surface is allowed to return a NULL ImpactI.
375 
376  const versions do not permit caching. */
377  ///@{
378 virtual sp<ImpactI> rayImpact(const SpatialTransform& a_transform,
379  const SpatialVector& a_origin,
380  const SpatialVector& a_direction,
381  Real a_maxDistance,
382  BWORD a_anyHit) =0;
383 virtual sp<ImpactI> rayImpact(const SpatialTransform& a_transform,
384  const SpatialVector& a_origin,
385  const SpatialVector& a_direction,
386  Real a_maxDistance,
387  BWORD a_anyHit) const =0;
388 
389 virtual sp<ImpactI> rayImpact(const SpatialVector& a_origin,
390  const SpatialVector& a_direction,
391  Real a_maxDistance,
392  BWORD a_anyHit) =0;
393 virtual sp<ImpactI> rayImpact(const SpatialVector& a_origin,
394  const SpatialVector& a_direction,
395  Real a_maxDistance,
396  BWORD a_anyHit) const =0;
397 
398 virtual sp<ImpactI> rayImpact(const SpatialVector& a_origin,
399  const SpatialVector& a_direction,
400  Real a_maxDistance) =0;
401 virtual sp<ImpactI> rayImpact(const SpatialVector& a_origin,
402  const SpatialVector& a_direction,
403  Real a_maxDistance) const =0;
404 
405 virtual Array< sp<SurfaceI::ImpactI> >
406  rayImpacts(const SpatialVector& a_origin,
407  const SpatialVector& a_direction,
408  Real a_maxDistance,U32 a_hitLimit) =0;
409 virtual Array< sp<SurfaceI::ImpactI> >
410  rayImpacts(const SpatialVector& a_origin,
411  const SpatialVector& a_direction,
412  Real a_maxDistance,U32 a_hitLimit) const=0;
413 
414 virtual sp<ImpactI> coneImpact(const SpatialTransform& a_transform,
415  const SpatialVector& a_origin,
416  const SpatialVector& a_direction,
417  Real a_maxDistance,Real a_coneAngle,
418  sp<DrawI> a_spDrawI) =0;
419 virtual sp<ImpactI> coneImpact(const SpatialVector& a_origin,
420  const SpatialVector& a_direction,
421  Real a_maxDistance,Real a_coneAngle,
422  sp<DrawI> a_spDrawI) =0;
423 
424 virtual sp<ImpactI> capsuleImpact(const SpatialTransform& a_transform,
425  const SpatialVector& a_origin,
426  const SpatialVector& a_direction,
427  Real a_maxDistance,Real a_radius,
428  BWORD a_anyHit,sp<DrawI> a_spDrawI,
429  sp<ImpactI> a_spLastImpact) =0;
430 virtual sp<ImpactI> capsuleImpact(const SpatialVector& a_origin,
431  const SpatialVector& a_direction,
432  Real a_maxDistance,Real a_radius,
433  BWORD a_anyHit,sp<DrawI> a_spDrawI,
434  sp<ImpactI> a_spLastImpact) =0;
435  ///@}
436 
437 virtual sp<GaugeI> gauge(void) =0;
438 
439 virtual void partitionWith(String a_attributeName) =0;
440 virtual U32 partitionCount(void) const =0;
441 virtual String partitionName(U32 a_index) const =0;
442 virtual Vector4 partitionSphere(U32 a_index) const =0;
443 virtual I32 setPartitionFilter(String a_filterString) =0;
444 virtual I32 setPartitionFilter(String a_filterString,
445  PartitionI::FilterMethod a_filterMethod)=0;
446 virtual sp<PartitionI> createPartition(void) =0;
447 };
448 
449 } /* namespace ext */
450 } /* namespace fe */
451 
452 #endif /* __surface_SurfaceI_h__ */
fe::ext::SurfaceI::GaugeI
calculate surface distances
Definition: SurfaceI.h:121
fe::ext::SurfaceI
Spatial boundary.
Definition: SurfaceI.h:20
fe::Counted
Heap-based support for classes participating in fe::ptr <>
Definition: Counted.h:35
fe::Instance
Smart pointer used with types represented by BaseType.
Definition: Instance.h:28
fe
kernel
Definition: namespace.dox:3
fe::Color
Special vector for color (RGBA)
Definition: Color.h:21
fe::String
Automatically reference-counted string container.
Definition: String.h:128
fe::ext::SurfaceI::ImpactI
results of a surface intersection
Definition: SurfaceI.h:60
fe::Array
Wrapper for std::vector.
Definition: Array.h:21
fe::Component
Base for all interfacable components.
Definition: Component.h:20
fe::sp
Intrusive Smart Pointer.
Definition: src/core/ptr.h:53
fe::CastableAs
Per-class participation non-RTTI fallback dynamic casting mechanism.
Definition: Castable.h:192
Generated by   doxygen 1.8.13