NDEVR
API Documentation
SnapController.h
1/*--------------------------------------------------------------------------------------------
2Copyright (c) 2019, NDEVR LLC
3tyler.parke@ndevr.org
4 __ __ ____ _____ __ __ _______
5 | \ | | | __ \ | ___|\ \ / / | __ \
6 | \ | | | | \ \ | |___ \ \ / / | |__) |
7 | . \| | | |__/ / | |___ \ V / | _ /
8 | |\ |_|_____/__|_____|___\_/____| | \ \
9 |__| \__________________________________| \__\
10
11Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants
12Licensee a limited, non-exclusive, non-transferable, royalty-free license
13(without the right to sublicense) to use the API solely for the purpose of
14Licensee's internal development efforts to develop applications for which
15the API was provided.
16
17The above copyright notice and this permission notice shall be included in all
18copies or substantial portions of the Software.
19
20THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
21INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
22PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
23FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
24OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25DEALINGS IN THE SOFTWARE.
26
27Library: Design
28File: SnapController
29Included in API: True
30Author(s): Tyler Parke
31 *-----------------------------------------------------------------------------------------**/
32#pragma once
33#include <NDEVR/SnapPoint.h>
34#include <NDEVR/MouseController.h>
35#if NDEVR_VIEWPORT
36#include <NDEVR/KeyController.h>
37#include <NDEVR/SelectionArea.h>
38#include <NDEVR/Plane.h>
39#include <NDEVR/TextConstructor.h>
40#include <functional>
41namespace NDEVR
42{
43
45
51 class NDEVR_DESIGN_API SnapController : public MouseControllerBase, public KeyControllerBase
52 {
53 public:
59 {
66 {
67 return all_text[dimension];
68 }
69 uint01 dimension = Constant<uint01>::Invalid;
70 uint04 cursor_position = Constant<uint04>::Invalid;
71 };
72
83
94 public:
100 virtual ~SnapController(){}
104 virtual void cancel();
105
112 virtual bool processMouseEvent(MouseControllerEvent& event, SelectionInfo& info) override;
120 virtual bool processKeyEvent(const KeyEvent& event, DesignObjectLookup* lookup, Camera* camera) override;
121
130 uint04 pointCount() const { return m_points.size(); }
135 virtual void setUpdateCallback(const std::function<void()>& callback) { m_update_callback = callback; }
141 virtual void setFinishedCallback(const std::function<void(bool is_accepted)>& callback) { m_finished_callback = callback; }
147 void lockAxis(uint01 axis, fltp08 lock) { m_lock_axis[axis] = lock; }
177 void setLockPlane(const Plane<3, fltp08>& plane);
182 void setCustomSnapManager(const ConstPointer<SnapsManager>& snap_manager) { m_custom_snap_manager = snap_manager; };
189 void setLocation(const Vertex<3, fltp08>& location, bool is_click = false, Camera* camera = nullptr);
194 void setShowLengthLabels(bool show);
199 void setShowPointLabels(bool show);
209 const Buffer<Vertex<3, fltp08>>& points() const { return m_points; }
220
222 protected:
231 virtual void addPoint(const Vertex<3, fltp08>& point);
236 virtual void addPoint(const SnapPoint& point);
240 virtual void begin();
244 virtual void finish();
251 virtual void updateLocation(const Vertex<3, fltp08>& location, bool is_click, Camera* camera);
283 void setGuidePoint(uint04 index, const Vertex<3, fltp08>& p1, const UUID& material);
291 void setGuidePlane(uint04 index, const Vector<3, fltp08>& normal, const Vertex<3, fltp08>& location, fltp08 radius);
299 void setGuideLine(uint04 index, const Vertex<3, fltp08>& p1, const Vector<3, fltp08>& p2, const UUID& material);
316 void setGuidePlaneVisible(bool visible);
322 void setGuidePlaneVisible(uint04 index, bool visible);
327 void setGuideLineVisible(bool visible);
333 void setGuideLineVisible(uint04 index, bool visible);
338 void setGuidePointVisible(bool visible);
344 void setGuidePointVisible(uint04 index, bool visible);
365 void updateRecentGeometry(const SnapPoint& point);
372 virtual void setupSelectionInfo(const MouseEvent& event, Camera* camera, SelectionInfo& info);
392 protected:
403
405 UUID m_current_line_material = Constant<UUID>::Invalid;
406
407 UUID m_free_point_material = Constant<UUID>::Invalid;
408 UUID m_point_material = Constant<UUID>::Invalid;
409 UUID m_edge_point_material = Constant<UUID>::Invalid;
410 UUID m_end_point_material = Constant<UUID>::Invalid;
411 UUID m_mid_point_material = Constant<UUID>::Invalid;
412 UUID m_center_point_material = Constant<UUID>::Invalid;
413 UUID m_on_face_point_material = Constant<UUID>::Invalid;
414
415 UUID m_free_line_material = Constant<UUID>::Invalid;
416 UUID m_locked_line_material = Constant<UUID>::Invalid;
417 UUID m_extend_line_material = Constant<UUID>::Invalid;
418 UUID m_perpendicular_line_material = Constant<UUID>::Invalid;
419 UUID m_tangent_line_material = Constant<UUID>::Invalid;
420 UUID m_red_line_material = Constant<UUID>::Invalid;
421 UUID m_green_line_material = Constant<UUID>::Invalid;
422 UUID m_blue_line_material = Constant<UUID>::Invalid;
423
424 UUID m_last_selection_camera= Constant<UUID>::Invalid;
425
426 UUID m_guide_model = Constant<UUID>::Invalid;
427 UUID m_plane_mesh = Constant<UUID>::Invalid;
428 UUID m_line_mesh = Constant<UUID>::Invalid;
429 UUID m_point_mesh = Constant<UUID>::Invalid;
433
436
440
446 std::function<void()> m_update_callback;
447 std::function<void(bool is_accepted)> m_finished_callback;
455 bool m_is_vertical_locked = false;
458 };
459}
460
461#endif
The equivelent of std::vector but with a bit more control.
Definition Buffer.hpp:58
A core object representing a user view as well as convenience functions for moving this view through ...
Definition Camera.h:95
Provides a constant, unmodifiable pointer that has shared ownership of a dynamically allocated object...
Definition Pointer.hpp:276
A core class where all Design Objects including models, materials, and geometries are stored.
Forward declaration for the camera class.
Describes a user key press event used to trigger behavior in the NDEVR API.
Definition Event.h:49
Class: LineSegment.
Definition Line.hpp:52
A core class that represents a node on model hierarchy.
Definition Model.h:292
A base class for adding functionality to the user mouse inputs.
Describes a mouse or touch input event with position, button, and modifier information.
Definition Event.h:316
Logic for a given plane or N-dimensions.
Definition Plane.hpp:53
A core part of the engine, stores variables that can be listened to with ResourceListener which will ...
Definition Resource.h:42
Responsible for turning a user interaction into a selection within a DesignObjectLookup.
Definition Selector.h:52
LockMode
Controls how axis/plane locking interacts with snapping behavior.
@ e_lock_ignore_snap
Ignores all snapping; lock takes full precedence.
@ e_lock_to_nearest_snap
First snaps, then constrains the result to the closest position along the lock.
@ e_only_allow_snap
Only allows snapped positions; ignores lock guides.
@ e_lock_if_no_snap
Only applies the lock constraint if no snap point is found.
@ e_ignore
Ignores lock guides entirely; snapping operates freely.
Buffer< SnapPoint > m_last_snap_points
The most recently computed set of candidate snap points.
UUID m_on_face_point_material
Material for snap points on faces.
PointsDrawMode
Determines how snapped points are drawn or connected visually in the viewport.
@ e_polyline
Draw points connected as a continuous polyline.
@ e_lines
Draw points connected as discrete line segments (pairs of vertices).
@ e_line_fan
Draw lines radiating from the first point to each subsequent point.
@ e_points
Draw individual unconnected points.
@ e_triangle
Draw points as filled triangles.
virtual void cancel()
Cancels the current snap operation and cleans up any active state or visuals.
bool m_is_using_lock_plane
Whether a lock plane is currently in use for constraining.
void setLocation(const Vertex< 3, fltp08 > &location, bool is_click=false, Camera *camera=nullptr)
Sets the current snap location, optionally registering it as a click.
UUID m_green_line_material
Material for Y-axis (green) guide lines.
std::function< void()> m_update_callback
Callback invoked when the snap state is updated.
virtual void addPoint(const Vertex< 3, fltp08 > &point)
Adds a 3D point to the accumulated points buffer.
SelectionMode m_selection_mode
The current selection mode used during interaction.
bool m_show_length_label
Whether length labels are displayed on guide lines.
Vertex< 3, fltp08 > m_lock_axis
Per-axis lock values (NaN or invalid means unlocked).
Model setupGuideModel()
Creates and returns a Model configured as a guide visual element.
DesignObjectLookup * m_manager
The DesignObjectLookup this controller operates on.
virtual bool processKeyEvent(const KeyEvent &event, DesignObjectLookup *lookup, Camera *camera) override
Processes an incoming keyboard event for snap-related shortcuts and dimension locking.
UUID m_point_mesh
UUID of the mesh used for guide points.
void setGuideLineVisible(uint04 index, bool visible)
Sets the visibility of a specific guide line by index.
UUID m_extend_line_material
Material for extension guide lines.
std::function< void(bool is_accepted)> m_finished_callback
Callback invoked when the snap operation finishes.
UUID m_perpendicular_line_material
Material for perpendicular guide lines.
void setLockPlane(const Plane< 3, fltp08 > &plane)
Sets a plane to constrain snap positions onto.
virtual void addPoint(const SnapPoint &point)
Adds a snap point (with snap metadata) to the accumulated points buffer.
bool m_show_location_label
Whether coordinate labels are displayed at snap points.
void lockAxis(uint01 axis, fltp08 lock)
Locks a specific axis to a fixed coordinate value.
uint04 pointCount() const
Returns the number of points currently recorded by the snap controller.
Buffer< UUID > m_guide_plane_material
Materials assigned to each guide plane.
Camera * m_last_camera
The camera used in the last event processing.
virtual void setFinishedCallback(const std::function< void(bool is_accepted)> &callback)
Sets a callback invoked when the snap operation finishes.
Buffer< UUID > m_point_guide_text
UUIDs of text labels attached to guide points.
void calcLockLineLocation(SnapPoint &point, const SelectionInfo &info)
Calculates the constrained snap point position along a lock line.
void setPointsDrawMode(PointsDrawMode mode)
Sets the visual draw mode for how accumulated points are rendered.
Buffer< std::pair< UUID, uint04 > > m_last_lines
Recently snapped line geometry (UUID and vertex index pairs).
LockMode m_lock_mode
The active lock mode controlling snap-lock interaction.
Buffer< Vertex< 3, fltp08 > > m_points
Accumulated 3D snap points from user clicks.
SelectionMode selectionMode() const
Returns the current selection mode.
MouseEvent m_last_mouse_event
The most recently processed mouse event.
virtual void begin()
Called when a snap operation begins.
void setGuidePlane(uint04 index, const Vector< 3, fltp08 > &normal, const Vertex< 3, fltp08 > &location, fltp08 radius)
Sets the orientation, position, and size of a guide plane at the given index.
Resource< SnapPoint > current_snap_point
The currently active snap point resource, updated as the mouse moves.
void setShowPointLabels(bool show)
Sets whether coordinate labels are displayed at snap points.
SnapPoint m_original_snap
The original snap point before lock adjustments.
void setGuideLine(uint04 index, const Vertex< 3, fltp08 > &p1, const Vector< 3, fltp08 > &p2, const UUID &material)
Sets the start position, direction, and material of a guide line at the given index.
const Buffer< SnapPoint > & lastSnapPoints() const
Returns the buffer of snap points from the most recent snap calculation.
UUID m_red_line_material
Material for X-axis (red) guide lines.
Plane< 3, fltp08 > m_lock_plane
The plane used for plane-lock constraining.
Vertex< 3, fltp08 > m_location
The current snap location in 3D space.
UUID pointMaterial(const SnapPoint &point)
Returns the material UUID appropriate for the given snap point type.
void setGuidePoint(uint04 index, const Vertex< 3, fltp08 > &p1, const UUID &material)
Sets the position and material of a guide point at the given index.
UUID m_point_material
Material for generic snap points.
UUID m_free_point_material
Material for free (unconstrained) snap points.
Buffer< UUID > m_line_guide_text
UUIDs of text labels attached to guide lines.
void setGuidePointVisible(uint04 index, bool visible)
Sets the visibility of a specific guide point by index.
SnapController(DesignObjectLookup *manager)
Constructs a SnapController associated with the given DesignObjectLookup.
UUID m_plane_mesh
UUID of the mesh used for guide planes.
virtual void setUpdateCallback(const std::function< void()> &callback)
Sets a callback invoked whenever the snap location or state is updated.
ConstPointer< SnapsManager > m_custom_snap_manager
Optional custom snap manager overriding default snap behavior.
UUID m_free_line_material
Material for free (unconstrained) guide lines.
bool m_is_vertical_locked
Whether vertical axis locking is currently active.
Buffer< std::pair< UUID, uint04 > > m_last_points
Recently snapped point geometry (UUID and vertex index pairs).
Vertex< 3, fltp08 > currentLocation() const
Returns the current snap location in 3D space.
LineSegment< 3, fltp08 > m_lock_line
The line segment used for line-lock constraining.
void setSelectionMode(SelectionMode mode)
Sets the selection mode used during snap interaction.
UUID m_center_point_material
Material for snap points at center points.
void setGuidePlaneVisible(uint04 index, bool visible)
Sets the visibility of a specific guide plane by index.
Buffer< UUID > m_guide_line_model
UUIDs of individual guide line models.
void addGuidePlaneModel()
Adds a guide plane model to the scene for visual feedback.
void addGuideLineModel()
Adds a guide line model to the scene for visual feedback.
bool m_is_active
Whether the snap controller is currently active.
void setShowLengthLabels(bool show)
Sets whether length labels are displayed along guide lines.
SnapPoint calcSnapPoint(const SelectionInfo &info, DesignObjectLookup *lookup)
Calculates the best snap point for the current selection context.
void drawDefaultGuidePlane(const SnapPoint &point)
Draws the default guide plane based on the current snap point context.
UUID m_edge_point_material
Material for snap points on edges.
Buffer< UUID > m_guide_line_material
Materials assigned to each guide line.
bool m_is_horizontal_locked
Whether horizontal axis locking is currently active.
void setLockLine(const LineSegment< 3, fltp08 > &line)
Sets a line segment to constrain snap positions along.
void setGuidePointVisible(bool visible)
Sets the visibility of all guide points.
Buffer< UUID > m_guide_point_model
UUIDs of individual guide point models.
virtual void setupSelectionInfo(const MouseEvent &event, Camera *camera, SelectionInfo &info)
Populates a SelectionInfo from the given mouse event and camera.
UUID m_guide_model
UUID of the root guide model in the scene.
UUID m_blue_line_material
Material for Z-axis (blue) guide lines.
DesignObjectLookup * m_last_lookup
The DesignObjectLookup used in the last event processing.
void calcLockPlaneLocation(SnapPoint &point, const SelectionInfo &info)
Calculates the constrained snap point position on a lock plane.
PointsDrawMode m_point_draw_mode
The current draw mode for accumulated points.
EditDimensionLockInformation m_user_edit
Current user dimension lock edit state.
UUID m_line_mesh
UUID of the mesh used for guide lines.
void clearSnapSelection()
Clears all currently accumulated snap selection points and resets the visual state.
void processUserInput()
Processes any pending user text input for dimension locking.
Buffer< UUID > m_guide_point_material
Materials assigned to each guide point.
UUID m_end_point_material
Material for snap points at endpoints.
void setCustomSnapManager(const ConstPointer< SnapsManager > &snap_manager)
Sets a custom snap manager to override the default snapping behavior.
virtual bool processMouseEvent(MouseControllerEvent &event, SelectionInfo &info) override
Processes an incoming mouse event for snapping and selection.
void setLockMode(LockMode mode)
Sets the lock mode that controls how axis/plane locking interacts with snapping.
bool processMouseSnap(MouseControllerEvent &event, SelectionInfo &info)
Processes a mouse event specifically for snapping logic.
UUID lineMaterial(const SnapPoint &point)
Returns the material UUID appropriate for the given snap point's guide line type.
Buffer< UUID > m_guide_plane_model
UUIDs of individual guide plane models.
UUID m_locked_line_material
Material for locked/constrained guide lines.
bool processMouseSelection(MouseControllerEvent &event)
Processes a mouse event for object selection (non-snap interaction).
void addGuidePointModel()
Adds a guide point model to the scene for visual feedback.
void setGuidePlaneVisible(bool visible)
Sets the visibility of all guide planes.
const Buffer< Vertex< 3, fltp08 > > & points() const
Returns the buffer of all accumulated snap points.
Vertex< 3, fltp08 > lastPoint() const
Returns the most recent snap location.
UUID m_tangent_line_material
Material for tangent guide lines.
UUID m_current_line_material
Material UUID for the current guide line being drawn.
Buffer< std::pair< UUID, uint04 > > m_last_meshes
Recently snapped mesh geometry (UUID and face index pairs).
void updateRecentGeometry(const SnapPoint &point)
Updates the recent geometry cache with the latest snap point for extending/snapping to nearby geometr...
Vertex< 3, fltp08 > m_lock_location
The reference location used for lock calculations.
virtual void updateLocation(const Vertex< 3, fltp08 > &location, bool is_click, Camera *camera)
Called when the snap location is updated.
void setGuideLineVisible(bool visible)
Sets the visibility of all guide lines.
void drawDefaultGuideLines(const SnapPoint &point)
Draws the default set of guide lines based on the current snap point context.
UUID m_last_selection_camera
UUID of the camera used in the last selection operation.
UUID m_mid_point_material
Material for snap points at midpoints.
virtual void finish()
Called when the snap operation is finished.
Contains information about a particular point of interest created from a user mouse interaction.
Definition SnapPoint.h:46
The core String class for the NDEVR API.
Definition String.h:95
A universally unique identifier (UUID) is a 128-bit number used to identify information in computer s...
Definition UUID.h:61
A fixed-size array with N dimensions used as the basis for geometric and mathematical types.
Definition Vector.hpp:62
A point in N-dimensional space, used primarily for spatial location information.
Definition Vertex.hpp:44
The primary namespace for the NDEVR SDK.
SelectionMode
uint32_t uint04
-Defines an alias representing a 4 byte, unsigned integer -Can represent exact integer values 0 throu...
double fltp08
Defines an alias representing an 8 byte floating-point number.
uint8_t uint01
-Defines an alias representing a 1 byte, unsigned integer -Can represent exact integer values 0 throu...
A wrapper for a mouse event that is used by MouseControllerBase.
Holds information about a user-initiated dimension lock edit, including per-axis text and the current...
uint01 dimension
The axis dimension currently being edited (0=X, 1=Y, 2=Z), or Invalid if none.
String & text()
Returns a reference to the text string for the currently active dimension.
Vector< 3, String > all_text
Text values for each of the three axes.
uint04 cursor_position
The cursor position within the text of the active dimension, or Invalid if unset.