KeyPath

class 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