Open 3D Engine SurfaceData Gem API Reference  24.09
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
SurfaceData::SurfacePointList Class Reference

#include <SurfacePointList.h>

Public Member Functions

 AZ_CLASS_ALLOCATOR (SurfacePointList, AZ::SystemAllocator)
 
 AZ_TYPE_INFO (SurfacePointList, "{DBA02848-2131-4279-BDEF-3581B76AB736}")
 
void Clear ()
 Clear the surface point list.
 
 SurfacePointList (AZStd::span< const AzFramework::SurfaceData::SurfacePoint > surfacePoints)
 
void StartListConstruction (AZStd::span< const AzFramework::SurfaceData::SurfacePoint > surfacePoints)
 
void StartListConstruction (AZStd::span< const AZ::Vector3 > inPositions, size_t maxPointsPerInput, AZStd::span< const SurfaceTag > filterTags)
 
void AddSurfacePoint (const AZ::EntityId &entityId, const AZ::Vector3 &inPosition, const AZ::Vector3 &position, const AZ::Vector3 &normal, const SurfaceTagWeights &weights)
 
void ModifySurfaceWeights (const SurfaceDataRegistryHandle &surfaceModifierHandle)
 
void EndListConstruction ()
 
bool IsEmpty () const
 
bool IsEmpty (size_t inputPositionIndex) const
 
size_t GetSize () const
 
size_t GetSize (size_t inputPositionIndex) const
 
size_t GetInputPositionSize () const
 
void EnumeratePoints (AZStd::function< bool(size_t inputPositionIndex, const AZ::Vector3 &position, const AZ::Vector3 &normal, const SurfaceTagWeights &surfaceWeights)> pointCallback) const
 
void EnumeratePoints (size_t inputPositionIndex, AZStd::function< bool(const AZ::Vector3 &position, const AZ::Vector3 &normal, const SurfaceTagWeights &surfaceWeights)> pointCallback) const
 
AzFramework::SurfaceData::SurfacePoint GetHighestSurfacePoint (size_t inputPositionIndex) const
 
AZ::Aabb GetSurfacePointAabb () const
 

Protected Member Functions

void FilterPoints (AZStd::span< const SurfaceTag > desiredTags)
 
size_t GetInPositionIndexFromPosition (const AZ::Vector3 &inPosition) const
 
size_t GetSurfacePointStartIndexFromInPositionIndex (size_t inPositionIndex) const
 

Protected Attributes

AZStd::span< const SurfaceTag > m_filterTags
 
AZStd::span< const AZ::Vector3 > m_inputPositions
 
size_t m_inputPositionSize = 0
 
size_t m_lastInputPositionIndex = 0
 
AZStd::vector< size_t > m_numSurfacePointsPerInput
 
AZ::Aabb m_surfacePointBounds = AZ::Aabb::CreateNull()
 
size_t m_maxSurfacePointsPerInput = 0
 
bool m_listIsBeingConstructed = false
 
AZStd::vector< size_t > m_sortedSurfacePointIndices
 
AZStd::vector< AZ::Vector3 > m_surfacePositionList
 
AZStd::vector< AZ::Vector3 > m_surfaceNormalList
 
AZStd::vector< SurfaceTagWeights > m_surfaceWeightsList
 
AZStd::vector< AZ::EntityId > m_surfaceCreatorIdList
 

Detailed Description

SurfacePointList stores a collection of surface point data, which consists of positions, normals, and surface tag weights. This class is specifically designed to be used in the following ways.

List construction: StartListConstruction() - This clears the structure, temporarily holds on to the list of input positions, and preallocates the data. AddSurfacePoint() - Add surface points to the list. They're expected to get added in input position order. ModifySurfaceWeights() - Modify the surface weights for the set of input points. FilterPoints() - Remove any generated surface points that don't fit the filter criteria EndListConstruction() - "Freeze" and compact the data.

List usage: Any of the query APIs can be used in any order after the list has finished being constructed.

This class is specifically designed around the usage patterns described above to minimize the amount of allocations and data shifting that needs to occur. There are some tricky bits that need to be accounted for:

  • Tracking which input positions each output point belongs to.
  • Support for merging similar surface points together, which causes us to keep them sorted for easier comparisons.
  • Each surface provider will add points in input position order, but we call each provider separately, so the added points will show up like (0, 1, 2, 3), (0, 1, 3), (0, 0, 1, 2, 3), etc. We don't want to call each surface provider per-point, because that incurs a lot of avoidable overhead in each provider.
  • Output points get optionally filtered out at the very end if they don't match any of the filter tags passed in.

The solution is that we always add new surface point data to the end of their respective vectors, but we also keep a helper structure that's a list of lists of sorted indices. We can incrementally re-sort the indices quickly without having to shift all the surface point data around.

Constructor & Destructor Documentation

◆ SurfacePointList()

SurfaceData::SurfacePointList::SurfacePointList ( AZStd::span< const AzFramework::SurfaceData::SurfacePoint >  surfacePoints)

Constructor for creating a SurfacePointList from a list of SurfacePoint data. Primarily used as a convenience for unit tests.

Parameters
surfacePoints- A set of SurfacePoint points to store in the SurfacePointList. Each point that's passed in will be treated as both the input and output position. The list will be fully constructed and queryable after this runs.

Member Function Documentation

◆ AddSurfacePoint()

void SurfaceData::SurfacePointList::AddSurfacePoint ( const AZ::EntityId &  entityId,
const AZ::Vector3 &  inPosition,
const AZ::Vector3 &  position,
const AZ::Vector3 &  normal,
const SurfaceTagWeights &  weights 
)

Add a surface point to the list. To use this method optimally, the points should get added in increasing inPosition index order.

Parameters
entityId- The entity creating the surface point.
inPosition- The input position that produced this surface point.
position- The position of the surface point.
normal- The normal for the surface point.
weights- The surface tags and weights for this surface point.

◆ EndListConstruction()

void SurfaceData::SurfacePointList::EndListConstruction ( )

End construction of the SurfacePointList. After this is called, surface points can no longer be added or modified, and all of the query APIs can start getting used.

◆ EnumeratePoints() [1/2]

void SurfaceData::SurfacePointList::EnumeratePoints ( AZStd::function< bool(size_t inputPositionIndex, const AZ::Vector3 &position, const AZ::Vector3 &normal, const SurfaceTagWeights &surfaceWeights)>  pointCallback) const

Enumerate every surface point and call a callback for each point found. Note: There is no guaranteed order to which the points will be enumerated. @pointCallback - The method to call with each surface point.

◆ EnumeratePoints() [2/2]

void SurfaceData::SurfacePointList::EnumeratePoints ( size_t  inputPositionIndex,
AZStd::function< bool(const AZ::Vector3 &position, const AZ::Vector3 &normal, const SurfaceTagWeights &surfaceWeights)>  pointCallback 
) const

Enumerate every surface point for a given input position and call a callback for each point found. Note: There is no guaranteed order to which the points will be enumerated. @inputPositionIndex - The input position to get the outputs for. @pointCallback - The method to call with each surface point.

◆ GetHighestSurfacePoint()

AzFramework::SurfaceData::SurfacePoint SurfaceData::SurfacePointList::GetHighestSurfacePoint ( size_t  inputPositionIndex) const

Get the surface point with the highest Z value for a given input position. @inputPositionIndex - The input position to get the highest surface point for.

Returns
The surface point with the highest Z value for the given input position.

◆ GetInputPositionSize()

size_t SurfaceData::SurfacePointList::GetInputPositionSize ( ) const
inline

Return the total number of input positions. Normally the caller would already be expected to know this, but in the case of using region-based queries, the number of input positions might not be entirely obvious.

Returns
The total number of input positions used to generate the outputs.

◆ GetSize() [1/2]

size_t SurfaceData::SurfacePointList::GetSize ( ) const

Return the total number of output points generated.

Returns
The total number of output points generated.

◆ GetSize() [2/2]

size_t SurfaceData::SurfacePointList::GetSize ( size_t  inputPositionIndex) const

Return the total number of output points generated from a specific input position index.

Parameters
inputPositionIndex- The input position to look for output points for.
Returns
The total number of output points generated from a specific input position index.

◆ GetSurfacePointAabb()

AZ::Aabb SurfaceData::SurfacePointList::GetSurfacePointAabb ( ) const
inline

Get the AABB that encapsulates all of the generated output surface points.

Returns
The AABB surrounding all the output surface points.

◆ IsEmpty() [1/2]

bool SurfaceData::SurfacePointList::IsEmpty ( ) const

Return whether or not the entire surface point list is empty.

Returns
True if empty, false if it contains any points.

◆ IsEmpty() [2/2]

bool SurfaceData::SurfacePointList::IsEmpty ( size_t  inputPositionIndex) const

Return whether or not a given input position index has any output points associated with it.

Parameters
inputPositionIndex- The input position to look for output points for.
Returns
True if empty, false if there is at least one output point associated with the input position.

◆ ModifySurfaceWeights()

void SurfaceData::SurfacePointList::ModifySurfaceWeights ( const SurfaceDataRegistryHandle &  surfaceModifierHandle)

Modify the surface weights for each surface point in the list.

Parameters
surfaceModifierHandle- The handle to the surface modifier that will modify the surface weights.

◆ StartListConstruction() [1/2]

void SurfaceData::SurfacePointList::StartListConstruction ( AZStd::span< const AZ::Vector3 >  inPositions,
size_t  maxPointsPerInput,
AZStd::span< const SurfaceTag >  filterTags 
)

Start construction of a SurfacePointList.

Parameters
inPositions- the list of input positions that will be used to generate this list. This list is expected to remain valid until EndListConstruction() is called.
maxPointsPerInput- the maximum number of potential surface points that will be generated for each input. This is used for allocating internal structures during list construction and is enforced to be correct.
filterTags- optional list of tags to filter the generated surface points by. If this list is provided, every surface point remaining in the list after construction will contain at least one of these tags. If the list is empty, all generated points will remain in the list. The filterTags list is expected to remain valid until EndListConstruction() is called.

◆ StartListConstruction() [2/2]

void SurfaceData::SurfacePointList::StartListConstruction ( AZStd::span< const AzFramework::SurfaceData::SurfacePoint >  surfacePoints)

Start construction of a SurfacePointList from a list of SurfacePoint data. Primarily used as a convenience for unit tests.

Parameters
surfacePoints- A set of SurfacePoint points to store in the SurfacePointList. The list will remain in the "constructing" state after this is called, so it will still be possible to add/modify points, and EndListConstruction() will still need to be called.
The documentation for this class was generated from the following file: