Ubuntu Wiki

Library: uTouch-Physics
Language: C
Dependencies: ODE, Geis

Units

Screen coordinates make more sense than real-world coordinates. If you have a 30" monitor next to a 24" monitor, both with equal resolutions, scrolling should move the content the same amount in screen coordinates. To facilitate this, units of pixels are used for distance in internal physics calculations. When real-world units are used, the library will convert them to pixels internally before performing computation.

A 24" 1080p monitor is a typical size and resolution for a desktop computer. This works out to 3614 px/m in the diagonal direction. We will assume square pixels. Thus, a reasonable conversion from meters to pixels is about 3.5 MP/m (where MP is a mega-pixel, or 1000 pixels).

Types

uphys

Handle for uTouch-Physics context.

uphys_units

Enum specifying a unit type.

Values:

• UPHYS_MILLIMETER
• UPHYS_PIXEL

uphys_point

Holds a point in two axes.

uphys_size

Holds dimensions in two axes of an object.

uphys Properties

error: int

Error code from last function call.

Set to 0 on success.

error_string: const char *

Error string from last function call.

Set to "no error" on success.

gravity: float

Defaults to 34.3 MP/s². This is calculated by multiplying the standard earth gravity of 9.8 m/s² by the standard conversion from meters to pixels of 3.5 MP/m.

mm_multiplier: float

Scalar multiplier applied to parameters given in UPHYS_MILLIMETER units. Defaults to value read from dconf settings repository if available, and then to TBD.

This is roughly equivalent to the sensitivity of a trackpad.

mu: float

Friction constant. Defaults to value read from dconf settings repository if available, and then to TBD.

(scrollview) viewport_origin: uphys_point

The origin point of the viewport of the scrollview.

The origin is defined as the point within the rectangle with the minimum values for both axes.

(scrollview) viewport_size: uphys_size

The size of the viewport of the scrollview.

(scrollview) content_origin: uphys_point

The origin point of the content of the scrollview.

The origin is defined as the point within the rectangle with the minimum values for both axes.

(scrollview) content_size: uphys_size

The size of the content of the scrollview.

Functions

int uphys_set_property(uphys *uphys, const char *name, void *value)

Set a property value.

Returns 0 if successful, non-zero on error.

int uphys_get_property(const uphys *uphys, const char *name, void *value)

Get a property value.

Returns 0 if successful, non-zero on error.

void uphys_inject(uphys *uphys, GeisEvent event)

Inject an input event.

An error will occur if the time of the event is earlier than the time of a previous uphys_update() call.

void uphys_update(uphys *uphys, time_t *time)

Perform simulation of model up to the time given.

uphys *uphys_new_scrollview()

Create a new uphys context for a scrollable viewport.

Returns a new context or NULL on error.

API Use Case Example

Implementing smooth scrolling in a document viewer.

Setup steps:

1. Create a uphys context using uphys_new_scrollview()
2. Set properties on the context for the origin and size of the content and viewport
3. Create a Geis context to receive drag events
4. Add a callback for uphys on the display refresh signal
   • - Use OpenGL sync signal if available - Otherwise use a static timer at a reasonable interval (maybe 30 Hz)

In Geis drag callbacks:

1. Call uphys_inject().
   • - For touchpads and independent devices use UPHYS_MILLIMETER units - For touchscreens use UPHYS_PIXEL units

In the uphys callback:

1. Call uphys_update() with the current time
2. Get the new viewport origin using uphys_get_property()
3. Redraw the scrollview