- Overview
- Files
- Related Pages
- Modules

TanvasTouch SDK - C Interface Documentation

# Overview

The TanvasTouch Engine C API manages haptic resources, which are used by the TanvasTouch Engine to direct the TanvasTouch Controller and touchscreen to render haptic textures. The TanvasTouch hardware renders textures by modulating friction under the operator's fingers.

# Getting started

All C API functions return a status code; status codes are documented in tanvastouch_errors.h. Most C API functions have one or more out-parameters that return resource IDs or attributes.

To use the C API, first open a context:

tanvastouch_ctx *ctx = NULL;
int rc = tanvastouch_open(engine_path, &ctx);
if (rc != TANVASTOUCH_OK) {
fprintf(stderr, "error: %s\n", tanvastouch_strerror(rc));
tanvastouch_close(ctx);
return -1;
}

Warning
  To check if a function succeeded, you must compare its result to TANVASTOUCH_OK. Checking for a nonzero result (`if (rc) { ... }`) is not correct.

With this context, you can create haptic resources. Each process has its own collection of haptic resources; these cannot be shared across processes.

tanvastouch_resource_id view_id = TANVASTOUCH_INVALID_RESOURCE_ID;
int rc = tanvastouch_create_view(ctx, &view_id);
if (rc != TANVASTOUCH_OK) {
fprintf(stderr, "error: %s\n", tanvastouch_strerror(rc));
tanvastouch_close(ctx);
return -1;
}

Finally, close the context when it's no longer needed:

tanvastouch_close(ctx);
return 0;

# Haptic resources are positioned using the window system's rules

The coordinate system for haptic resources is provided by the window system. Details for supported systems are given below. The Engine works in either logical or physical pixels depending on what is most convenient for mapping touch inputs to positions on the virtual desktop.

## The coordinate system for Windows 10

- X increases to the right and Y increases going down. For views, the point (0, 0) is at top-left corner of the main display. For sprites, the point (0, 0) is the top-left corner of their parent view.
- The Engine runs in Per-Monitor v2 DPI awareness mode and therefore operates in physical pixels.

It is recommended that applications interacting with the Engine also use Per-Monitor V2 or Per-Monitor DPI awareness modes. For more information, see the MSDN article "High DPI Desktop Application Development on Windows": https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows

# Notes on API behavior

## Resource-related API call return value

API calls that set or fetch properties of haptic resources typically return the following values:

- TANVASTOUCH_OK: Set or fetch succeeded
- TANVASTOUCH_ERROR_RESOURCE_UNKNOWN: A resource ID passed to the API function does not map to a known resource for the calling process
- TANVASTOUCH_ERROR_ENGINE_OPERATION_FAILED: The engine could not apply the requested change

## Out-parameters are only written on success

Most of the API calls that write data to out-parameters will write data if and only if the return value of the call is TANVASTOUCH_OK. On failure, the original contents of the pointed-to storage will not be modified.

## Destructors do not clear resource IDs

Destructor functions do not clear application-side copies of resource IDs. It is safe to keep these IDs around, but any modifications or queries done with those IDs will return TANVASTOUCH_ERROR_RESOURCE_UNKNOWN.

TANVASTOUCH_OK
#define TANVASTOUCH_OK
Definition: tanvastouch_errors.h:48
tanvastouch_close
TANVASTOUCH_API int tanvastouch_close(tanvastouch_ctx *ctx)
tanvastouch_ctx
struct tanvastouch_ctx tanvastouch_ctx
Definition: tanvastouch.h:157
tanvastouch_resource_id
uint64_t tanvastouch_resource_id
Definition: tanvastouch.h:166
TANVASTOUCH_INVALID_RESOURCE_ID
#define TANVASTOUCH_INVALID_RESOURCE_ID
Definition: tanvastouch_errors.h:41
tanvastouch_open
TANVASTOUCH_API int tanvastouch_open(const char *engine_name, tanvastouch_ctx **p_ctx)
tanvastouch_create_view
TANVASTOUCH_API int tanvastouch_create_view(tanvastouch_ctx *ctx, tanvastouch_resource_id *p_view_id)
tanvastouch_strerror
const TANVASTOUCH_API char * tanvastouch_strerror(int err)