Mapping API
Mapping represents a set of device's elements mapped on 2d space.
Elements are described by the 2D Polygon - an array of points. Elements are bound to bones, a full set of bones is included in a layout, multiple layouts with the same element types are contained in an array, an array of layouts with same type are packed by TsLayout2dType and TsLayout2dElementType. Mappings might have different versions. Mapping can be requested by a mapping version or by a device handler because each device has a bound mapping version by default.
For example, a path to get shapes of all electric haptic channels would be:
ts_mapping2d_get_by_devicefor attached devicets_mapping2d_get_number_of_layoutsfor device mappingts_mapping2d_get_layoutswith preallocated array of received number of layouts- check is received array contains
TsLayout2dType== Electric andTsLayout2dElementType== Channel ts_mapping2d_layout_get_number_of_bonesfor layout withTsLayout2dType== Electric andTsLayout2dElementType== Channelts_mapping2d_layout_get_boneswith preallocated array of received number of bones- for each bone handler
ts_mapping2d_bone_get_number_of_contents ts_mapping2d_bone_get_contents- for each bone content
ts_mapping2d_bone_content_get_number_of_points ts_mapping2d_bone_content_get_pointswith preallocated array of received number of points
Functions#
ts_mapping2d_get_by_device#
TsStatusCode ts_mapping2d_get_by_device(TsDeviceHandle* dev, TsMapping2d* mapping);Gets the default 2D mapping handle bound to an attached device.
Preconditions
Parameters
dev: TsDeviceHandle*, in
handle to the attached device whose default mapping should be retrieved
mapping: TsMapping2d*, out
pointer to a variable that receives the resulting mapping handle
Returns: TsStatusCode
TsStatusCode indicating whether the mapping was resolved successfully
ts_mapping2d_get_by_version#
TsStatusCode ts_mapping2d_get_by_version(TsMapping2dVersion version, TsMapping2d* mapping);Gets a 2D mapping handle for a specific mapping version.
Preconditions
Parameters
version: TsMapping2dVersion, in
identifier of the mapping version to retrieve, see TsMapping2dVersion
mapping: TsMapping2d*, out
pointer to a variable that receives the resulting mapping handle
Returns: TsStatusCode
TsStatusCode indicating whether the mapping was resolved successfully
ts_mapping2d_get_number_of_layouts#
TsStatusCode ts_mapping2d_get_number_of_layouts(const TsMapping2d mapping, uint64_t* number_of_layouts);Gets the number of layouts contained in a mapping.
Preconditions
Parameters
mapping: const TsMapping2d, in
handle to the mapping object whose layouts should be counted
number_of_layouts: uint64_t*, out
pointer to a variable that receives the number of layouts in the mapping
Returns: TsStatusCode
TsStatusCode indicating whether the layout count was retrieved successfully
ts_mapping2d_get_layouts#
TsStatusCode ts_mapping2d_get_layouts(const TsMapping2d mapping, TsLayout2d* layouts, uint64_t number_of_layouts);Gets all layout handles contained in a mapping.
Preconditions
Parameters
mapping: const TsMapping2d, in
handle to the mapping object whose layouts should be retrieved
layouts: TsLayout2d*, out
pointer to a preallocated array that receives the layout handles
number_of_layouts: uint64_t, in
number of elements allocated in the layouts array, as returned by ts_mapping2d_get_number_of_layouts
Returns: TsStatusCode
TsStatusCode indicating whether the layouts were retrieved successfully
ts_mapping2d_layout_get_index#
TsStatusCode ts_mapping2d_layout_get_index(TsLayout2d layout, uint8_t* layout_index);Gets the index of a layout within its type group.
Preconditions
Parameters
layout: TsLayout2d, in
handle to the layout object whose index should be retrieved
layout_index: uint8_t*, out
pointer to a variable that receives the layout's index within its type group
Returns: TsStatusCode
TsStatusCode indicating whether the layout index was retrieved successfully
ts_mapping2d_layout_get_type#
TsStatusCode ts_mapping2d_layout_get_type(const TsLayout2d layout, TsLayout2dType* layout_type);Gets the layout type of a layout.
Preconditions
Parameters
layout: const TsLayout2d, in
handle to the layout object whose type should be retrieved
layout_type: TsLayout2dType*, out
pointer to a variable that receives the layout's TsLayout2dType value
Returns: TsStatusCode
TsStatusCode indicating whether the layout type was retrieved successfully
ts_mapping2d_layout_get_element_type#
TsStatusCode ts_mapping2d_layout_get_element_type(const TsLayout2d layout, TsLayout2dElementType* element_type);Gets the element type of a layout.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_get_layouts
Parameters
layout: const TsLayout2d, in
handle to the layout object whose element type should be retrieved
element_type: TsLayout2dElementType*, out
pointer to a variable that receives the layout's TsLayout2dElementType value
Returns: TsStatusCode
TsStatusCode indicating whether the element type was retrieved successfully
ts_mapping2d_layout_get_number_of_bones#
TsStatusCode ts_mapping2d_layout_get_number_of_bones(const TsLayout2d layout, uint64_t* number_of_bones);Gets the number of bones referenced by a layout.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_get_layouts
Parameters
layout: const TsLayout2d, in
handle to the layout object whose bones should be counted
number_of_bones: uint64_t*, out
pointer to a variable that receives the number of bones in the layout
Returns: TsStatusCode
TsStatusCode indicating whether the bone count was retrieved successfully
ts_mapping2d_layout_get_bones#
TsStatusCode ts_mapping2d_layout_get_bones(const TsLayout2d layout, TsMapping2dBone* bones, uint64_t number_of_bones);Gets the bones referenced by a layout.
Preconditions
Parameters
layout: const TsLayout2d, in
handle to the layout object whose bones should be retrieved
bones: TsMapping2dBone*, out
pointer to a preallocated array that receives the bone handles
number_of_bones: uint64_t, in
number of elements allocated in the bones array, as returned by ts_mapping2d_layout_get_number_of_bones
Returns: TsStatusCode
TsStatusCode indicating whether the bones were retrieved successfully
ts_mapping2d_bone_get_index#
TsStatusCode ts_mapping2d_bone_get_index(const TsMapping2dBone bone, TsBoneIndex* bone_index);Gets the skeletal index of a bone.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_layout_get_bones
Parameters
bone: const TsMapping2dBone, in
handle to the bone object whose index should be retrieved
bone_index: TsBoneIndex*, out
pointer to a variable that receives the bone's skeletal index
Returns: TsStatusCode
TsStatusCode indicating whether the bone index was retrieved successfully
See also: ts_mapping2d_layout_get_bones
ts_mapping2d_bone_get_side#
TsStatusCode ts_mapping2d_bone_get_side(const TsMapping2dBone bone, TsBone2dSide* bone_side);Gets the surface side of a bone.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_layout_get_bones
Parameters
bone: const TsMapping2dBone, in
handle to the bone object whose surface side should be retrieved
bone_side: TsBone2dSide*, out
pointer to a variable that receives the bone's TsBone2dSide value
Returns: TsStatusCode
TsStatusCode indicating whether the bone side was retrieved successfully
ts_mapping2d_bone_get_number_of_contents#
TsStatusCode ts_mapping2d_bone_get_number_of_contents(const TsMapping2dBone bone, uint64_t* number_of_contents);Gets the number of content entries mapped to a bone.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_layout_get_bones
Parameters
bone: const TsMapping2dBone, in
handle to the bone object whose content entries should be counted
number_of_contents: uint64_t*, out
pointer to a variable that receives the number of content entries for the bone
Returns: TsStatusCode
TsStatusCode indicating whether the content count was retrieved successfully
ts_mapping2d_bone_get_contents#
TsStatusCode ts_mapping2d_bone_get_contents(const TsMapping2dBone bone, TsMapping2dBoneContent* bone_contents, uint64_t number_of_bone_contents);Gets the content entries (cells or channels) mapped to a bone.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_bone_get_number_of_contents
Parameters
bone: const TsMapping2dBone, in
handle to the bone object whose content entries should be retrieved
bone_contents: TsMapping2dBoneContent*, out
pointer to a preallocated array that receives the bone content handles
number_of_bone_contents: uint64_t, in
number of elements allocated in the bone_contents array, as returned by ts_mapping2d_bone_get_number_of_contents
Returns: TsStatusCode
TsStatusCode indicating whether the bone content entries were retrieved successfully
ts_mapping2d_bone_content_get_number_of_points#
TsStatusCode ts_mapping2d_bone_content_get_number_of_points(const TsMapping2dBoneContent bone_content, uint64_t* number_of_points);Gets the number of shape points describing a bone content element.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_bone_get_contents
Parameters
bone_content: const TsMapping2dBoneContent, in
handle to the bone content object (cell or channel) whose points should be counted
number_of_points: uint64_t*, out
pointer to a variable that receives the number of points describing the element's shape
Returns: TsStatusCode
TsStatusCode indicating whether the point count was retrieved successfully
ts_mapping2d_bone_content_get_points#
TsStatusCode ts_mapping2d_bone_content_get_points(const TsMapping2dBoneContent bone_content, TsVec2f* points, uint64_t number_of_points);Gets the 2D polygon points describing a bone content element's shape.
Preconditions
ts_initialize or ts_initialize_with_path, ts_mapping2d_bone_content_get_number_of_points
Parameters
bone_content: const TsMapping2dBoneContent, in
handle to the bone content object (cell or channel) whose shape points should be retrieved
points: TsVec2f*, out
pointer to a preallocated array that receives the polygon points
number_of_points: uint64_t, in
number of elements allocated in the points array, as returned by ts_mapping2d_bone_content_get_number_of_points
Returns: TsStatusCode
TsStatusCode indicating whether the shape points were retrieved successfully