mirror of
https://gitlab.com/kicad/code/kicad.git
synced 2024-11-22 09:25:02 +00:00
c99a4f4d85
The commit only adds the headers and code required by the SpaceMouse implementation to compile and link. This extract from the 3Dconnexion SDK is added to the third party directory to allow developers to build without needing to acquire a cmake enabled version.
636 lines
28 KiB
C
636 lines
28 KiB
C
#ifndef NAVLIB_H_INCLUDED_
|
|
#define NAVLIB_H_INCLUDED_
|
|
/*
|
|
* This program source code file is part of KiCad, a free EDA CAD application.
|
|
*
|
|
* Copyright (c) 2014-2021 3Dconnexion.
|
|
*
|
|
* This program is free software: you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License as published by the
|
|
* Free Software Foundation, either version 3 of the License, or (at your
|
|
* option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful, but
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/**
|
|
* @file navlib.h
|
|
* @brief describes the interface for navigating in a 2D or 3D view.
|
|
*/
|
|
|
|
#include <navlib/navlib_types.h>
|
|
/// <summary>
|
|
/// Contains the navigation library API types and functions
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The functions and types describe an interface for navigating in a 2D or 3D view.
|
|
/// <para>
|
|
/// In this scheme, a 3dconnexion library is responsible for calculating the position of the camera
|
|
/// viewing the scene or object as well as displaying the settings and for supporting user
|
|
/// customization.
|
|
/// </para>
|
|
/// <para>
|
|
/// The application is responsible for passing the description of an interface of the 2D/3D view to
|
|
/// the 3dconnexion library, and for reacting to the changes to the properties identified by the
|
|
/// 3dconnexion library.
|
|
/// </para>
|
|
/// </remarks>
|
|
_NAVLIB_BEGIN
|
|
|
|
// ************************************************************************************************
|
|
// Properties
|
|
|
|
/// <summary>
|
|
/// Property set by the client to indicate that the connection is currently active.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>Clients that have multiple navigation instances open need to inform the navlib which of
|
|
/// them is the target for 3D Mouse input. They do this by setting the active_k property of a
|
|
/// navigation instance to true.</para>
|
|
/// </remarks>
|
|
static const property_t active_k = "active";
|
|
|
|
/// <summary>
|
|
/// Property that a client sets to indicate it has keyboard focus.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>Clients that run in container applications via the NLServer proxy set this property to
|
|
/// indicate keyboard focus. This will set 3DMouse focus to the navlib connection.</para>
|
|
/// </remarks>
|
|
static const property_t focus_k = "focus";
|
|
|
|
/// <summary>
|
|
/// Client property that the navlib sets when a motion model is active.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>The motion_k property is set to true by the navlib to notify
|
|
/// the client that it is executing a motion model and will update the camera matrix regularly. This
|
|
/// is useful for clients that need to run an animation loop. When the navlib has finished
|
|
/// navigating the camera position it will set the property to false. By setting motion_k to false,
|
|
/// a client may temporarily interrupt a navigation communication and force the Navlib to
|
|
/// reinitialize the navigation.</para>
|
|
/// </remarks>
|
|
static const property_t motion_k = "motion";
|
|
|
|
/// <summary>
|
|
/// Specifies the transform from the client's coordinate system to the navlib coordinate system.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="matrix_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="matrix_type"/>.</para>
|
|
/// <para>The Navigation Library coordinate system is Y up, X to the right and Z out of the screen.
|
|
/// This property is queried directly after new navigation instance is created. This allows the
|
|
/// client to specify the other properties using the coordinate system used in the client. For the
|
|
/// keep Y up ('Lock Horizon') algorithm to work correctly a non-identity matrix needs to be
|
|
/// specified whenever the ground plane is not the X-Z plane.</para>
|
|
/// </remarks>
|
|
static const property_t coordinate_system_k = "coordinateSystem";
|
|
|
|
/* Frame properties*/
|
|
/// <summary>
|
|
/// Specifies the begin and end of a navigation transaction.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="long"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="long_type"/>.</para>
|
|
/// <para>The Navigation Library can set more than one client property for a single navigation
|
|
/// frame. For example when navigating in an orthographic projection possibly both the view affine
|
|
/// and extents will be modified depending on the 3DMouse input. The Navigation Library sets the
|
|
/// transaction_k property to a value >0 at the beginning of a navigation frame and to 0 at the end.
|
|
/// Clients that need to actively refresh the view can trigger the refresh when the value is set to
|
|
/// 0.</para>
|
|
/// </remarks>
|
|
static const property_t transaction_k = "transaction";
|
|
|
|
/// <summary>
|
|
/// Specifies the time stamp of an animation frame in milliseconds.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="double"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="double_type"/>.</para>
|
|
/// <para>When the frame_timing_source_k property is set to 1, the client initiates a frame
|
|
/// transaction by informing the Navigation Library of the frame time. When the value is 0, the
|
|
/// Navigation Library attempts to synchronize the frames to the monitor vertical blanking
|
|
/// rate.</para>
|
|
/// </remarks>
|
|
static const property_t frame_time_k = "frame.time";
|
|
|
|
/// <summary>
|
|
/// Specifies the source of the frame timing.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="long"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="long_type"/>.</para>
|
|
/// <para>By setting the frame_timing_source_k property to 1, the client application informs the
|
|
/// Navigation Library that the client has an animation loop and will be the source of the frame
|
|
/// timing.</para>
|
|
/// </remarks>
|
|
static const property_t frame_timing_source_k = "frame.timingSource";
|
|
|
|
/// <summary>
|
|
/// Specifies whether a device is present
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>Currently this always returns true.</para>
|
|
/// </remarks>
|
|
static const property_t device_present_k = "device.present";
|
|
|
|
/// <summary>
|
|
/// Defines a set of commands.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="SiActionNode_t"/>* and <see cref="propertyType_t"/> is
|
|
/// <see cref="actionnodeexptr_type"/>.</para>
|
|
/// <para>Command sets can be considered to be button banks. The set can be either the complete list
|
|
/// of commands that are available in the application or a single set of commands for a specific
|
|
/// application context. The navlib will not query the application for this property. It is the
|
|
/// responsibility of the application to update this property when commands are to be made available
|
|
/// to the user.</para>
|
|
/// </remarks>
|
|
static const property_t commands_tree_k = "commands.tree";
|
|
|
|
/// <summary>
|
|
/// The active command.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="string_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="string_type"/>.</para>
|
|
/// <para>When the user presses a 3DMouse button that has been assign an application command
|
|
/// exposed by the commands_tree_k property, the navlib will write this property. The string value
|
|
/// will be the corresponding id passed in the commands_tree_k property. Generally the navlib will
|
|
/// set this property to an empty string when the corresponding button has been released.</para>
|
|
/// </remarks>
|
|
static const property_t commands_activeCommand_k = "commands.activeCommand";
|
|
|
|
/// <summary>
|
|
/// Specifies the active set of commands.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="string_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="string_type"/>.</para>
|
|
/// <para>In applications that have exposed multiple command sets this property needs to be set to
|
|
/// define the command set that is active. The navlib will not query the application for this
|
|
/// property. It is the responsibility of the application to update this property when the set of
|
|
/// commands need to be changed. Normally this will be due to change in application state and may
|
|
/// correspond to a menu/toolbar change. If only a single set of commands has been defined, this
|
|
/// property defaults to that set.</para>
|
|
/// </remarks>
|
|
static const property_t commands_activeSet_k = "commands.activeSet";
|
|
|
|
/// <summary>
|
|
/// Specifies an array of images for the 3Dconnexion UI.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="imagearray_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="imagearray_type"/>.</para>
|
|
/// <para>An image with the same <see cref="SiImage_t.id"/> as a command
|
|
/// <see cref="SiActionNodeEx_t.id"/> will be associated with that command in the 3Dconnexion
|
|
/// UI.</para>
|
|
/// </remarks>
|
|
static const property_t images_k = "images";
|
|
|
|
/* view properties */
|
|
/// <summary>
|
|
/// Specifies the transformation matrix of the view camera.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="matrix_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="matrix_type"/>.</para>
|
|
/// <para>This matrix specifies the camera to world transformation of the view. That is,
|
|
/// transforming the position (0, 0, 0) by this matrix yields the position of the camera in world
|
|
/// coordinates. The navlib will, generally, query this matrix at the beginning of a navigation
|
|
/// action and then set the property once per frame.</para>
|
|
/// </remarks>
|
|
static const property_t view_affine_k = "view.affine";
|
|
|
|
/// <summary>
|
|
/// Specifies the plane equation of the construction plane.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="plane_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="plane_type"/>.</para>
|
|
/// <para>The plane equation is used by the Navigation Library to distinguish views used for
|
|
/// construction in orthographic projections: typically the top, right left etc. views. The
|
|
/// Navigation Library assumes that when the camera's look-at axis is parallel to the plane normal,
|
|
/// the view should not be rotated.</para>
|
|
/// </remarks>
|
|
static const property_t view_constructionPlane_k = "view.constructionPlane";
|
|
|
|
/// <summary>
|
|
/// Specifies the orthographic extents of the view in camera coordinates.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="box_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="box_type"/>.</para>
|
|
/// <para>The orthographic extents of the view are returned as a bounding box in world units
|
|
/// relative to the camera/view frame. The view frame is a right-handed coordinate system centered
|
|
/// on the view with x to the right and y up. The Navigation Library will only access this property
|
|
/// if the view is orthographic.</para>
|
|
/// </remarks>
|
|
static const property_t view_extents_k = "view.extents";
|
|
|
|
/// <summary>
|
|
/// Specifies the vertical field-of-view of a perspective camera/view in radians.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="double"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="double_type"/>.</para>
|
|
/// </remarks>
|
|
static const property_t view_fov_k = "view.fov";
|
|
|
|
/// <summary>
|
|
/// Specifies the frustum of a perspective camera/view in camera coordinates.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="frustum_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="frustum_type"/>.</para>
|
|
/// <para>The navlib uses this property to calculate the field-of-view of the perspective camera.
|
|
/// The frustum is also used in algorithms that need to determine if the model is currently visible.
|
|
/// The navlib will not write to this property. Instead, if necessary, the navlib will write to the
|
|
/// <see cref="view_fov_k"/> property and leave the client to change the frustum as it
|
|
/// wishes.</para>
|
|
/// </remarks>
|
|
static const property_t view_frustum_k = "view.frustum";
|
|
|
|
/// <summary>
|
|
/// Specifies whether the projection type of the view/camera is perspective.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>This property defaults to true. If the client does not supply a function for the navlib to
|
|
/// query the view's projection (which it will generally do at the onset of motion), then it must
|
|
/// set the property in the navlib if the projection is orthographic or when it changes.</para>
|
|
/// </remarks>
|
|
static const property_t view_perspective_k = "view.perspective";
|
|
|
|
/// <summary>
|
|
/// Specifies the position of the target of the view/camera.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="point_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="point_type"/>.</para>
|
|
/// <para>The view interest.</para>
|
|
/// </remarks>
|
|
static const property_t view_target_k = "view.target";
|
|
|
|
/// <summary>
|
|
/// Specifies whether the view can be rotated.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>This property is generally used to differentiate between orthographic 3D views and views
|
|
/// that can only be panned and zoomed such as plan views.</para>
|
|
/// </remarks>
|
|
static const property_t view_rotatable_k = "view.rotatable";
|
|
|
|
/// <summary>
|
|
/// Specifies the orientation of the view designated as the front view.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="matrix_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="matrix_type"/>.</para>
|
|
/// <para>The Navigation Library will only query the value of this property when the connection is
|
|
/// created. It is used to orientate the model to one of the 'Front', 'Back', 'Right', 'Left' etc.
|
|
/// views in response to the respective pre-defined view commands. If the orientation of the front
|
|
/// view is redefined after the connection is opened by the user, the client application is required
|
|
/// to update the property to the new value.</para>
|
|
/// </remarks>
|
|
static const property_t views_front_k = "views.front";
|
|
|
|
/// <summary>
|
|
/// Specifies the position of the rotation pivot.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="point_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="point_type"/>.</para>
|
|
/// <para>The Navigation Library will generally set <see cref="pivot_position_k"/> property when
|
|
/// navigation ends. The position will depend on which pivot model is being used. The application
|
|
/// can set the pivot to a fix position by setting this property. A side effect of the application
|
|
/// setting the property is that the <see cref="pivot_user_k"/> property is set to true.</para>
|
|
/// </remarks>
|
|
static const property_t pivot_position_k = "pivot.position";
|
|
|
|
/// <summary>
|
|
/// Specifies whether the position of the rotation pivot is set by the user.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="point_type"/>.</para>
|
|
/// <para>With the property set to true, the Navigation Library will disable the internal pivot
|
|
/// position algorithms.</para>
|
|
/// </remarks>
|
|
static const property_t pivot_user_k = "pivot.user";
|
|
|
|
/// <summary>
|
|
/// Specifies whether the rotation pivot widget is visible.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>Set by the Navigation Library when it wants to set the visibility of the pivot used for
|
|
/// the 3D navigation. This will be dependent on the user setting for the pivot visibility in the
|
|
/// 3Dconnexion Properties configuration and whether the Navigation Library is actively navigating
|
|
/// the scene.</para>
|
|
/// </remarks>
|
|
static const property_t pivot_visible_k = "pivot.visible";
|
|
|
|
/// <summary>
|
|
/// Specifies the origin of the ray used for hit-testing.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="point_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="point_type"/>.</para>
|
|
/// <para>Set by the Navigation Library. The location is relative to the world coordinate
|
|
/// system.</para>
|
|
/// </remarks>
|
|
static const property_t hit_lookfrom_k = "hit.lookfrom";
|
|
|
|
/// <summary>
|
|
/// Specifies the direction of the ray used for hit-testing.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="vector_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="vector_type"/>.</para>
|
|
/// <para>Set by the Navigation Library. The direction is relative to the world coordinate
|
|
/// system frame.</para>
|
|
/// </remarks>
|
|
static const property_t hit_direction_k = "hit.direction";
|
|
|
|
/// <summary>
|
|
/// Specifies the diameter of the ray used for hit-testing.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="double"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="double_type"/>.</para>
|
|
/// <para>Set by the Navigation Library. This is the diameter of the aperture on the frustum near
|
|
/// plane. In a perspective project the ray is a cone.</para>
|
|
/// </remarks>
|
|
static const property_t hit_aperture_k = "hit.aperture";
|
|
|
|
/// <summary>
|
|
/// Specifies the point of the model that is hit by the ray originating from
|
|
/// <see cref="hit_lookfrom_k"/>.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="point_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="point_type"/>.</para>
|
|
/// <para>This property is queried by the navlib. The navlib will generally calculate if it is
|
|
/// possible to hit a part of the model from the <see cref="model_extents_k"/> and
|
|
/// <see cref="selection_extents_k"/> properties before setting up the hit-test properties and
|
|
/// querying the property. The position is relative to the world coordinate system frame.</para>
|
|
/// </remarks>
|
|
static const property_t hit_lookat_k = "hit.lookat";
|
|
|
|
/// <summary>
|
|
/// Specifies whether the hit-testing is limited solely to the current selection set.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// </remarks>
|
|
static const property_t hit_selectionOnly_k = "hit.selectionOnly";
|
|
|
|
/// <summary>
|
|
/// Specifies the transformation matrix of the selection set.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="matrix_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="matrix_type"/>.</para>
|
|
/// <para>This matrix specifies the object to world transformation of the selection set. That is,
|
|
/// transforming the position (0, 0, 0) by this matrix yields the position of the set in world
|
|
/// coordinates. The navlib will, generally, query this matrix at the beginning of a navigation
|
|
/// action that involves moving the selection and then set the property once per frame.</para>
|
|
/// </remarks>
|
|
static const property_t selection_affine_k = "selection.affine";
|
|
|
|
/// <summary>
|
|
/// Specifies whether the selection set is empty.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="bool_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="bool_type"/>.</para>
|
|
/// <para>When true, nothing is selected.</para>
|
|
/// </remarks>
|
|
static const property_t selection_empty_k = "selection.empty";
|
|
|
|
/// <summary>
|
|
/// Specifies the bounding box of the selection set.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="box_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="box_type"/>.</para>
|
|
/// <para>The extents of the selection are returned as a bounding box in world coordinates. The
|
|
/// Navigation Library will only access this property if the <see cref="selection_empty_k"/>
|
|
/// property is false.</para>
|
|
/// </remarks>
|
|
static const property_t selection_extents_k = "selection.extents";
|
|
|
|
/// <summary>
|
|
/// Specifies the bounding box of the model.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="box_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="box_type"/>.</para>
|
|
/// </remarks>
|
|
static const property_t model_extents_k = "model.extents";
|
|
|
|
/// <summary>
|
|
/// Specifies the position of the mouse cursor. on the projection plane in world coordinates.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="point_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="point_type"/>.</para>
|
|
/// <para>The position of the mouse cursor is in world coordinates on the projection plane. For a
|
|
/// perspective projection the Navigation Library uses the near clipping as the projection plane.
|
|
/// In OpenGL the position would typically be retrieved using gluUnProject with winZ set to
|
|
/// 0.0.</para>
|
|
/// </remarks>
|
|
static const property_t pointer_position_k = "pointer.position";
|
|
|
|
/// <summary>
|
|
/// V3DK press event.
|
|
/// </summary>
|
|
static const property_t events_keyPress_k = "events.keyPress";
|
|
|
|
/// <summary>
|
|
/// V3DK release event.
|
|
/// </summary>
|
|
static const property_t events_keyRelease_k = "events.keyRelease";
|
|
|
|
/// <summary>
|
|
/// Used to query and apply settings in the 3Dconnexion Properties UI.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="string_t"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="string_type"/>.</para>
|
|
/// <para>The property settings_k does not actually exist in the Navigation Library. To read or
|
|
/// write a property to the application profile, the settings_k needs to be appended with "." and
|
|
/// the name of the profile property.<example>"settings.MoveObjects" is used to read or write the
|
|
/// value of the "MoveObjects" property in the profile settings.</example></para>
|
|
/// </remarks>
|
|
static const property_t settings_k = "settings";
|
|
|
|
/// <summary>
|
|
/// Specifies the change revision of the profile settings.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>The type is <see cref="long"/> and <see cref="propertyType_t"/> is
|
|
/// <see cref="long_type"/>.</para>
|
|
/// <para>This property is incremented when the settings changed. The value is only valid for the
|
|
/// current connection to the Navigation Library and is not persistent over multiple sessions. If
|
|
/// the client needs to know the value of a 3Dconnexion profile setting it should re-read the value
|
|
/// when settings_changed_k is changed.</para>
|
|
/// </remarks>
|
|
static const property_t settings_changed_k = "settings.changed";
|
|
|
|
// Workaround for error C2099: initializer is not a constant when compiling .c
|
|
#if __cplusplus
|
|
/// <summary>
|
|
/// Defines the type of a property and the access required of the client application.
|
|
/// </summary>
|
|
static const propertyDescription_t propertyDescription[] = {
|
|
/* property, type, required client access */
|
|
{active_k, bool_type, eno_access},
|
|
{focus_k, bool_type, eno_access},
|
|
{motion_k, bool_type, ewrite_access},
|
|
{coordinate_system_k, matrix_type, eread_access},
|
|
{device_present_k, bool_type, eno_access},
|
|
{events_keyPress_k, long_type, ewrite_access},
|
|
{events_keyRelease_k, long_type, ewrite_access},
|
|
|
|
/* frame properties*/
|
|
{transaction_k, long_type, ewrite_access},
|
|
{frame_time_k, double_type, eread_access},
|
|
{frame_timing_source_k, long_type, eread_access},
|
|
|
|
/* view properties */
|
|
{view_affine_k, matrix_type, eread_write_access},
|
|
{view_constructionPlane_k, plane_type, eread_access},
|
|
{view_extents_k, box_type, eread_write_access},
|
|
{view_fov_k, float_type, eread_write_access},
|
|
{view_frustum_k, frustum_type, eread_access},
|
|
{view_perspective_k, bool_type, eread_access},
|
|
{view_rotatable_k, bool_type, eread_access},
|
|
{view_target_k, point_type, eread_access},
|
|
|
|
/* views properties*/
|
|
{views_front_k, matrix_type, eread_access},
|
|
|
|
/* pivot properties */
|
|
{pivot_position_k, point_type, eread_write_access},
|
|
{pivot_user_k, bool_type, eno_access},
|
|
{pivot_visible_k, bool_type, ewrite_access},
|
|
|
|
/* hit-test properties */
|
|
{hit_lookfrom_k, point_type, ewrite_access},
|
|
{hit_direction_k, vector_type, ewrite_access},
|
|
{hit_aperture_k, float_type, ewrite_access},
|
|
{hit_lookat_k, point_type, eread_access},
|
|
{hit_selectionOnly_k, bool_type, ewrite_access},
|
|
|
|
/* selection properties */
|
|
{selection_affine_k, matrix_type, eread_write_access},
|
|
{selection_empty_k, bool_type, eread_access},
|
|
{selection_extents_k, box_type, eread_access},
|
|
|
|
/* model properties */
|
|
{model_extents_k, box_type, eread_access},
|
|
|
|
/* pointer (cursor) properties */
|
|
{pointer_position_k, point_type, eread_access},
|
|
|
|
/* commands properties */
|
|
{commands_tree_k, actionnodeexptr_type, eno_access},
|
|
{commands_activeSet_k, string_type, eno_access},
|
|
{commands_activeCommand_k, string_type, ewrite_access},
|
|
|
|
/* images properties*/
|
|
{images_k, imagearray_type, eno_access},
|
|
|
|
/* settings property*/
|
|
{settings_k, string_type, eno_access},
|
|
{settings_changed_k, long_type, ewrite_access}};
|
|
#endif
|
|
|
|
/**********************************************************************************************
|
|
Functions exported from the library
|
|
**********************************************************************************************/
|
|
|
|
/// <summary>
|
|
/// Creates a new navigation instance.
|
|
/// </summary>
|
|
/// <remarks>The client specifies the name of the instance and the properties that are available
|
|
/// for querying and updating by the navigation framework.</remarks>
|
|
/// <param name="pnh">A pointer to a <see cref="nlHandle_t"/> for the new navigation
|
|
/// instance.</param>
|
|
/// <param name="appname">The name of the application.</param>
|
|
/// <param name="property_accessors">An array of <see cref="accessor_t"/> structures containing the
|
|
/// property name, accessor and mutator functions that the client exposes to the navigation
|
|
/// instance.</param>
|
|
/// <param name="accessor_count">The number of <see cref="accessor_t"/> entries passed in the
|
|
/// property_accessors parameter.</param>
|
|
/// <param name="options">Pointer to a <see cref="nlCreateOptions_t"/>. This parameter is optional
|
|
/// and may be null.</param>
|
|
/// <returns>0 on success or a navlib error, see <see cref="navlib_errc::navlib_errc_t"/> and
|
|
/// <see cref="make_result_code"/>.</returns>
|
|
_NAVLIB_DLLAPI long __cdecl NlCreate(nlHandle_t *pnh, const char *appname,
|
|
const accessor_t property_accessors[], size_t accessor_count,
|
|
const nlCreateOptions_t *options);
|
|
|
|
/// <summary>
|
|
/// Closes an open navigation instance handle and destroys the navigation instance.
|
|
/// </summary>
|
|
/// <param name="nh">A valid <see cref="nlHandle_t"/> of an open navigation instance.</param>
|
|
/// <returns>0 if the function succeeds, otherwise a navlib error, see
|
|
/// <see cref="navlib_errc::navlib_errc_t"/> and <see cref="make_result_code"/>.</returns>
|
|
_NAVLIB_DLLAPI long __cdecl NlClose(nlHandle_t nh);
|
|
|
|
/// <summary>
|
|
/// Read the value of a property cached in the navlib.
|
|
/// </summary>
|
|
/// <param name="nh">The <see cref="nlHandle_t"/> of the open navigation instance.</param>
|
|
/// <param name="name">The name of the property whose value is being queried.</param>
|
|
/// <param name="value">A pointer to a <see cref="value_t"/> that contains the property value when
|
|
/// the function returns.</param>
|
|
/// <returns>0 if the function succeeds, otherwise a navlib error, see
|
|
/// <see cref="navlib_errc::navlib_errc_t"/> and <see cref="make_result_code"/>.</returns>
|
|
_NAVLIB_DLLAPI long __cdecl NlReadValue(nlHandle_t nh, property_t name, value_t *value);
|
|
|
|
/// <summary>
|
|
/// Write the value for a property to the navlib.
|
|
/// </summary>
|
|
/// <param name="nh">The <see cref="nlHandle_t"/> of the open navigation instance.</param>
|
|
/// <param name="name">The name of the property whose value is to be written.</param>
|
|
/// <param name="value">A pointer to a <see cref="value_t"/> that contains the new property
|
|
/// value.</param>
|
|
/// <returns>0 if the function succeeds, otherwise a navlib error, see
|
|
/// <see cref="navlib_errc::navlib_errc_t"/> and <see cref="make_result_code"/>.</returns>
|
|
_NAVLIB_DLLAPI long __cdecl NlWriteValue(nlHandle_t nh, property_t name, const value_t *value);
|
|
|
|
/// <summary>
|
|
/// Query the type of a navlib property.
|
|
/// </summary>
|
|
/// <param name="name">The name of the property whose type is to be queried.</param>
|
|
/// <returns>One of the <see cref="propertyTypes"/> values.</returns>
|
|
_NAVLIB_DLLAPI propertyType_t __cdecl NlGetType(property_t name);
|
|
|
|
_NAVLIB_END
|
|
|
|
#endif // NAVLIB_H_INCLUDED_
|