KeyPath

class HPS::KeyPath : public HPS::Object

The KeyPath contains an array of keys, organized from leaf to root. It allows the user to perform a number of queries along that path including accumulating net attributes and converting coordinates.

Public Types

using const_iterator = HPS::KeyArray::const_iterator
using const_reverse_iterator = HPS::KeyArray::const_reverse_iterator
using iterator = HPS::KeyArray::iterator
using reverse_iterator = HPS::KeyArray::reverse_iterator

Public Functions

KeyPath &Append(Key const &in_key)

Appends the supplied Key into this object. Same as operator+= function.

Deprecated:

This function exists for compatibility. Use KeyPath::PushBack instead.

Parameters

in_key – The Key to be appended to this.

Returns

A reference to this object.

KeyPath &Append(KeyArray const &in_key_array)

Appends the supplied key into this object. Same as operator+= function.

Deprecated:

This function exists for compatibility. Use KeyPath::PushBack instead.

Parameters

in_key_array – The KeyArray to be appended to this.

Returns

A reference to this object.

KeyPath &Append(KeyPath const &in_key_path)

Appends the supplied key into this object. Same as operator+= function.

Deprecated:

This function exists for compatibility. Use KeyPath::PushBack instead.

Parameters

in_key_path – The KeyPath to be appended to this.

Returns

A reference to this object.

Key &At(size_t in_index)

Access a Key in this KeyPath object. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters

in_index – The index of the Key to access, zero based.

Returns

The Key at position in_index in this key path.

Key const &At(size_t in_index) const

Access a Key in this KeyPath object. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters

in_index – The index of the Key to access, zero based.

Returns

The Key at position in_index in this key path.

Key &Back()

Returns the last key of this key path. An HPS::IndexOutOfRangeException exception is thrown if the key path is empty.

Returns

The last key of this key path.

Key const &Back() const

Returns the last key of this key path. An HPS::IndexOutOfRangeException exception is thrown if the key path is empty.

Returns

The last key of this key path.

iterator begin()

Returns an iterator pointing to the first Key contained in this Key Path

Returns

An iterator pointing to the first Key contained in this Key Path.

const_iterator begin() const

Returns a constant iterator pointing to the first Key contained in this Key Path

Returns

A constant iterator pointing to the first Key contained in this Key Path.

const_iterator cbegin() const

Returns a constant iterator pointing to the first Key contained in this Key Path

Returns

A constant iterator pointing to the first Key contained in this Key Path.

const_iterator cend() const

Returns a constant iterator pointing to the last Key contained in this Key Path

Returns

A constant iterator pointing to the last Key contained in this Key Path.

bool ComputeExtent(HPS::Extent::ClipRegion in_clip, Rectangle &out_extent) const

Computes a tight 2D extents box around the geometry contained in this key path. A user can use this information to tightly fit a camera to a specified segment or draw a 2D box around the segment. The coordinates are returned to the user in screen space.

Parameters
  • in_clip – The setting which indicates whether clip regions should be ignored or included.

  • out_extent – The screen extent of the geometry under this key path.

Returns

true if the operation succeeded, false otherwise.

bool ComputeExtent(HPS::VisibilityKit const &in_vis, HPS::Extent::ClipRegion in_clip, Rectangle &out_extent) const

Computes a tight 2D extents box around the geometry contained in this key path. A user can use this information to tightly fit a camera to a specified segment or draw a 2D box around the segment. The coordinates are returned to the user in screen space.

Parameters
  • in_vis – Explicit visibility settings to acknowledge instead of using the visibilities resolved by this key path.

  • in_clip – The setting which indicates whether clip regions should be ignored or included.

  • out_extent – The screen extent of the geometry under this key path.

Returns

true if the operation succeeded, false otherwise.

bool ComputeExtent(HPS::VisibilityKit const &in_vis, Rectangle &out_extent) const

Computes a tight 2D extents box around the geometry contained in this key path. A user can use this information to tightly fit a camera to a specified segment or draw a 2D box around the segment. The coordinates are returned to the user in screen space.

Parameters
  • in_vis – Explicit visibility settings to acknowledge instead of using the visibilities resolved by this key path.

  • out_extent – The screen extent of the geometry under this key path.

Returns

true if the operation succeeded, false otherwise.

bool ComputeExtent(Rectangle &out_extent) const

Computes a tight 2D extents box around the geometry contained in this key path. A user can use this information to tightly fit a camera to a specified segment or draw a 2D box around the segment. The coordinates are returned to the user in screen space.

Parameters

out_extent – The screen extent of the geometry under this key path.

Returns

true if the operation succeeded, false otherwise.

bool ComputeTextExtent(char const *in_text, float &out_xfrac, float &out_yfrac) const

Computes the extents of the specified text string based on the effective text attributes along this key path. If the effective text transform setting is Text::Transform::Transformable, the returned values will be in object space units. For any other effective text transform setting, the returned values will be a fraction of the segment window from 0.0 to 1.0 (or more) along this key path.

Parameters
  • in_text – The text to measure along this keypath

  • out_xfrac – The width of the text extent

  • out_yfrac – The height of the text extent

Returns

true if the operation succeeded, false otherwise.

bool ComputeTextMetrics(char const *in_text, TextMetrics::Options options, TextMetrics::Units size, FloatArray &out_metrics) const

Computes the extents of the specified text string based on effective text attributes along this key path in a variety of way based on the input options. The metrics will be returned as a fraction of the segment window from 0.0 to 1.0 along this key path.

Parameters
  • in_text – The text to measure along this keypath

  • options – The metrics you want returned to you in out_metrics

  • size – The space of the metrics returned. Currently only a fraction of the segment window.

  • out_metrics – The text extents of the text under this keypath in the format requested by options.

Returns

true if the operation succeeded, false otherwise.

bool ComputeTransform(Coordinate::Space in_space, Coordinate::Space in_output_space, HPS::MatrixKit &out_matrix) const

Computes the matrix which transforms objects from the input space to the output space along this key path.

Parameters
  • in_space – The starting or input coordinate space.

  • in_output_space – The final or output coordinate space.

  • out_matrix – The matrix which transforms objects from the input space to the output space.

Returns

true if the operation succeeded, false otherwise.

bool ConvertCoordinate(Coordinate::Space in_space, Point const &in_point, Coordinate::Space in_output_space, Point &out_point) const

Converts a point from one coordinate space to another using the transforms along this key path.

Parameters
  • in_space – The coordinate space of the input point.

  • in_point – The input point to convert.

  • in_output_space – The coordinate space to convert the input point into.

  • out_point – The output point, after conversion.

Returns

true if the operation succeeded, false otherwise.

bool ConvertCoordinate(Coordinate::Space in_space, PointArray const &in_points, Coordinate::Space in_output_space, PointArray &out_points) const

Converts a point from one coordinate space to another using the transforms along this key path.

Parameters
  • in_space – The coordinate space of the input point.

  • in_points – The input points to convert.

  • in_output_space – The coordinate space to convert the input point into.

  • out_points – The output points, after conversion.

Returns

true if the operation succeeded, false otherwise.

virtual bool Empty() const

Returns whether the key path is empty.

Returns

true if the key path is empty, false otherwise.

iterator end()

Returns an iterator pointing to the last Key contained in this Key Path

Returns

An iterator pointing to the last Key contained in this Key Path.

const_iterator end() const

Returns a constant iterator pointing to the last Key contained in this Key Path

Returns

A constant iterator pointing to the last Key contained in this Key Path.

bool Equals(KeyPath const &in_that) const

Check if the source KeyPath is equivalent to this object.

Parameters

in_that – The source KeyPath to compare to this object.

Returns

true if the objects are equivalent, false otherwise.

Key &Front()

Returns the first key of this key path. An HPS::IndexOutOfRangeException exception is thrown if the key path is empty.

Returns

The first key of this key path.

Key const &Front() const

Returns the first key of this key path. An HPS::IndexOutOfRangeException exception is thrown if the key path is empty.

Returns

The first key of this key path.

size_t GatherCutGeometry(SegmentKey const &in_destination, CutGeometryGatheringOptionsKit const &in_options) const

Collects capping geometry generated by cutting planes. Geometry is deposited in the segment you specify. Note: Capping geometry is generated during an update. Until an update is completed, no geometry will be present to gather.

Parameters
  • in_destination – A segment that the capping geometry will be deposited into.

  • in_options – Options for the gathering operation.

Returns

The number of individual caps created.

void Insert(size_t in_index, Key const &in_item)

Inserts in_item in the key path before the element at position in_index, increasing the size of the key path by one. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters
  • in_index – The index where in_item will be inserted

  • in_item – The key to insert in this key path.

KeyPath()

Creates an uninitialized key path that refers to no database objects.

KeyPath(KeyArray const &in_path)

Creates a new KeyPath object based on the supplied path.

Parameters

in_path – An array of keys arranged from leaf to root.

KeyPath(KeyPath &&in_that)

The move constructor creates a KeyPath by transferring the underlying impl of the rvalue reference to this KeyPath thereby avoiding a copy and allocation.

Parameters

in_that – An rvalue reference to a KeyPath to take the impl from.

KeyPath(KeyPath const &in_that)

Copies in_that into this key path.

KeyPath(size_t in_path_count, Key const in_path[])

Creates a new KeyPath object based on the supplied path.

Parameters
  • in_path_count – The number of keys in the array.

  • in_path – An array of keys arranged from leaf to root.

inline virtual HPS::Type ObjectType() const

This function returns the type the object, as declared (if the object is derived, this does not give the true type of the derived object).

Returns

The declared type of the object in question, which may differ from the true, underlying type.

bool operator!=(KeyPath const &in_that) const

Check if the source KeyPath is not equivalent to this object.

Parameters

in_that – The source KeyPath to compare to this object.

Returns

true if the objects are not equivalent, false otherwise.

KeyPath &operator+=(Key const &in_key)

Appends the supplied Key into this object. Same as Append function.

Parameters

in_key – The key to be appended to this.

Returns

A reference to this object.

KeyPath &operator+=(KeyArray const &in_key_array)

Appends the supplied KeyArray into this object. Same as Append function.

Parameters

in_key_array – The KeyArray to be appended to this.

Returns

A reference to this object.

KeyPath &operator+=(KeyPath const &in_key_path)

Appends the supplied KeyPath into this object. Same as Append function.

Parameters

in_key_path – The KeyPath to be appended to this.

Returns

A reference to this object.

KeyPath &operator=(KeyArray const &in_path)

Copies an array of keys into this object.

Parameters

in_path – The source array, assumed to be arranged from leaf to root.

Returns

A reference to this object.

KeyPath &operator=(KeyPath &&in_that)

The move assignment operator transfers the underlying impl of the rvalue reference to this KeyPath thereby avoiding a copy.

Parameters

in_that – An rvalue reference to a KeyPath to take the impl from.

Returns

A reference to this KeyPath.

KeyPath &operator=(KeyPath const &in_that)

Copies the supplied path into this object.

Parameters

in_that – The source of the copy.

Returns

A reference to this object.

bool operator==(KeyPath const &in_that) const

Check if the source KeyPath is equivalent to this object.

Parameters

in_that – The source KeyPath to compare to this object.

Returns

true if the objects are equivalent, false otherwise.

Key PopBack()

Returns the last key of this key path and returns it. An HPS::IndexOutOfRangeException exception is thrown if the key path is empty.

Returns

The last key of this key path.

Key PopFront()

Returns the first key of this key path and returns it. An HPS::IndexOutOfRangeException exception is thrown if the key path is empty.

Returns

The first key of this key path.

KeyPath &PushBack(Key const &in_key)

Adds in_key to the end of the key path.

Parameters

in_key – The key to add to the end of the key path.

Returns

A reference to this object.

KeyPath &PushBack(KeyArray const &in_key_array)

Appends the supplied key into this object. Same as operator+= function.

Parameters

in_key_array – The KeyArray to be appended to this.

Returns

A reference to this object.

KeyPath &PushBack(KeyPath const &in_key_path)

Appends the keys contained in the supplied key path at the end of this key path

Parameters

in_key_path – The KeyPath to be appended to this.

Returns

A reference to this object.

KeyPath &PushFront(Key const &in_key)

Adds in_key to the front of the key path.

Parameters

in_key – The key to add to the front of the key path.

Returns

A reference to this object.

reverse_iterator rbegin()

Returns a reverse iterator pointing to the last Key contained in this Key Path

Returns

A reverse iterator pointing to the last Key contained in this Key Path.

const_reverse_iterator rbegin() const

Returns a constant reverse iterator pointing to the last Key contained in this Key Path

Returns

A constant reverse iterator pointing to the last Key contained in this Key Path.

void Remove(Key const &in_item)

Traverses the keys in this key path and removes the first one which matches in_item NOTE: A useful KeyPath should not contain duplicate keys.

Parameters

in_item – The item to remove from the key path.

void Remove(size_t in_index)

Removes the the key at position in_index from this key path. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters

in_index – The index of the key to remove, zero based.

reverse_iterator rend()

Returns a reverse iterator pointing to the first Key contained in this Key Path

Returns

A reverse iterator pointing to the first Key contained in this Key Path.

const_reverse_iterator rend() const

Returns a constant iterator pointing to the first Key contained in this Key Path

Returns

A constant iterator pointing to the first Key contained in this Key Path.

KeyPath Reverse() const

Creates and returns a new KeyPath object, with the keys organized in the reverse order.

Returns

A new KeyPath object, containing keys organized in the reverse order.

void Set(KeyPath const &in_that)

Copies the supplied path into this object.

Parameters

in_that – The source of the copy.

KeyPath &SetKeys(KeyArray const &in_keys)

Copies an array of keys into this object.

Parameters

in_keys – The source array, assumed to be arranged from leaf to root.

Returns

A reference to this object.

KeyPath &SetKeys(size_t in_key_count, Key const in_keys[])

Copies an array of keys into this object.

Parameters
  • in_key_count – the number of keys in the array.

  • in_keys – The source array, assumed to arranged from leaf to root.

Returns

A reference to this object.

bool ShowEffectiveGlyphDefinition(char const *in_name, GlyphDefinition &out_def) const

Shows the effective glyph definition belonging to the input name along this key path.

Parameters
  • in_name – UTF8-encoded name of the glyph to find along this key path.

  • out_def – The effective glyph definition, if any, with the specified name along this key path.

Returns

true if the glyph definition exists along this path, false otherwise.

bool ShowEffectiveImageDefinition(char const *in_name, ImageDefinition &out_def) const

Shows the effective image definition belonging to the input name along this key path.

Parameters
  • in_name – UTF8-encoded name of the image to find along this key path.

  • out_def – The effective image definition, if any, with the specified name along this key path.

Returns

true if the image definition exists along this path, false otherwise.

bool ShowEffectiveLegacyShaderDefinition(char const *in_name, LegacyShaderDefinition &out_def) const

Shows the effective legacy shader definition belonging to the input name along this key path.

Parameters
  • in_name – UTF8-encoded name of the legacy shader to find along this key path.

  • out_def – The effective legacy shader definition, if any, with the specified name along this key path.

Returns

true if the legacy shader definition exists along this path, false otherwise.

bool ShowEffectiveLinePatternDefinition(char const *in_name, LinePatternDefinition &out_def) const

Shows the effective line pattern definition belonging to the input name along this key path.

Parameters
  • in_name – UTF8-encoded name of the line pattern to find along this key path.

  • out_def – The effective material line pattern, if any, with the specified name along this key path.

Returns

true if the line pattern definition exists along this path, false otherwise.

bool ShowEffectiveMaterialPaletteDefinition(char const *in_name, MaterialPaletteDefinition &out_def) const

Shows the effective material palette definition belonging to the input name along this key path.

Parameters
  • in_name – UTF8-encoded name of the material palette to find along this key path.

  • out_def – The effective material palette definition, if any, with the specified name along this key path.

Returns

true if the material palette definition exists along this path, false otherwise.

bool ShowEffectiveTextureDefinition(char const *in_name, TextureDefinition &out_def) const

Shows the effective texture definition belonging to the input name along this key path.

Parameters
  • in_name – UTF8-encoded name of the texture to find along this key path.

  • out_def – The effective texture definition, if any, with the specified name along this key path.

Returns

true if the texture definition exists along this path, false otherwise.

bool ShowKeys(KeyArray &out_keys) const

Shows the keys defining this key path.

Returns

true if the setting is valid, false otherwise.

bool ShowNetAttributeLock(AttributeLockKit &out_kit) const

Shows the net attribute lock settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetBounding(bool in_consider_highlights, BoundingKit &out_kit) const

Shows the net bounding along this key path. This function also optionally includes the bounding for geometry affected by in-place highlighting. This includes Show, Hide, and Isolate operations which alter visibility. In order for all highlights to be accounted for, the KeyPath should be complete, extending from the leaf segment or geometry, all the way to the WindowKey or Canvas.

Parameters

in_consider_highlights – If true, geometry with attributes set by in-place highlighting (including those attributes affecting visibility) will be included in the boundary calculation.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetBounding(BoundingKit &out_kit) const

Shows the net bounding along this key path without taking into account attributes set through highlights.

Deprecated:

This function exists for compatibility and ShowNetBounding(bool, BoundingKit &) should be preferred. This function will be removed in HPS 2021.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetCamera(CameraKit &out_kit) const

Shows the net camera attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetClipRegions(PointArrayArrayArray &out_loops_array, ClipSpaceArray &out_spaces, ClipOperationArray &out_operations, MatrixKitArray &out_matrices) const

Collects all clip regions on key path.

Parameters
  • out_loops_array – An array of arrays of loops describing the clip region.

  • out_spaces – An array of the coordinate spaces in which loops are described.

  • out_operations – An array of the operations performed by the clip regions.

  • out_matrices – An array of the matrices used by the clip regions if they are in ClipSpace::Object else identity matrix.

Returns

true if clip regions exist along this path, false otherwise.

bool ShowNetColorInterpolation(ColorInterpolationKit &out_kit) const

Shows the net color interpolation attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetConditions(UTF8Array &out_conditions) const

Shows the net condition settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetContourLine(ContourLineKit &out_kit) const

Shows the net contour line attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetCulling(CullingKit &out_kit) const

Shows the net culling attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetCurveAttribute(CurveAttributeKit &out_kit) const

Shows the net curve attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetCuttingSectionAttribute(CuttingSectionAttributeKit &out_kit) const

Shows the net cutting section attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetCylinderAttribute(CylinderAttributeKit &out_kit) const

Shows the net cylinder attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetDrawingAttribute(DrawingAttributeKit &out_kit) const

Shows the net drawing attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetEdgeAttribute(EdgeAttributeKit &out_kit) const

Shows the net edge attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetHiddenLineAttribute(HiddenLineAttributeKit &out_kit) const

Shows the net hidden line attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetLightingAttribute(LightingAttributeKit &out_kit) const

Shows the net lighting attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetLineAttribute(LineAttributeKit &out_kit) const

Shows the net line attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetMarkerAttribute(MarkerAttributeKit &out_kit) const

Shows the net marker attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetMaterialMapping(MaterialMappingKit &out_kit) const

Shows the net material mapping attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetMaterialPalette(UTF8 &out_name) const

Shows the material palette name along this key path.

Returns

true if a material palette is set along this path, false otherwise.

bool ShowNetModellingMatrix(MatrixKit &out_kit) const

Shows the net modelling matrix attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetNURBSSurfaceAttribute(NURBSSurfaceAttributeKit &out_kit) const

Shows the net NURBS surface attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetPBRMaterial(PBRMaterialKit &out_kit) const

Shows the net pbr material attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetPerformance(PerformanceKit &out_kit) const

Shows the net performance attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetPixelShader(PixelShaderKey &out_shader, HPS::Shader::Primitives in_target) const

Shows the net pixel shader along this key path.

Returns

false if no pixel shader exists along this key path.

bool ShowNetPixelShaderUniformData(HPS::Shader::Primitives in_primitives, ByteArray &out_data) const

Shows the net pixel shader uniform data along this key path.

Returns

false if no pixel shader data exists along this key path.

bool ShowNetSelectability(SelectabilityKit &out_kit) const

Shows the net selectability attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetSphereAttribute(SphereAttributeKit &out_kit) const

Shows the net sphere attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetSubwindow(SubwindowKit &out_kit) const

Shows the net subwindow attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetTextAttribute(TextAttributeKit &out_kit) const

Shows the net text attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetTextureMatrix(MatrixKit &out_kit) const

Shows the net texture matrix attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetTransformMask(TransformMaskKit &out_kit) const

Shows the net transform mask attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetTransparency(TransparencyKit &out_kit) const

Shows the net transparency attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetVertexShader(VertexShaderKey &out_shader, HPS::Shader::Primitives in_target) const

Shows the net vertex shader along this key path. return false if no vertex shader exists along this key path.

bool ShowNetVertexShaderUniformData(HPS::Shader::Primitives in_primitives, ByteArray &out_data) const

Shows the net vertex shader uniform data along this key path.

Returns

false if no vertex shader data exists along this key path.

bool ShowNetVisibility(VisibilityKit &out_kit) const

Shows the net visibility attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

bool ShowNetVisualEffects(VisualEffectsKit &out_kit) const

Shows the net visual effects attribute settings along this key path.

Returns

true if the setting is valid along this path, false otherwise.

size_t Size() const

Returns the number of Keys contained in this KeyPath object.

Returns

the number of keys in this key path.

KeyPath &UnsetKeys()

Removes the keys defining this key path.

Returns

A reference to this object.

virtual ~KeyPath()

Releases a reference to the database object this object is tied to.

Public Static Attributes

static const HPS::Type staticType = HPS::Type::KeyPath