Physics

Differences between revisions 1 and 26 (spanning 25 versions)
⇤ ← Revision 1 as of 2011-08-11 16:36:21 →
Size: 1391
Editor: c-71-237-195-76
Comment:
← Revision 26 as of 2011-08-18 10:26:38 → ⇥
Size: 6805
Editor: xdsl-83-145-207-155
Comment: Overview ok
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Library: uTouch-Physics
Language: C
Dependencies: [[http://opende.sourceforge.net/wiki/index.php/Main_Page|ODE]]		 Library: uTouch-Physics<<BR>>
Language: C (Maybe built on top of GLib? Qt already depends on GLib by default if available.)<<BR>>
Dependencies: possibly a physics engine such as [[http://code.google.com/p/chipmunk-physics/|Chipmunk]]
Line 5: Line 5:
== 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.		 '''''Note''''': This page is in the process of being rewritten. It will be inconsistent until this task is finished.
Line 8: Line 7:
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). <<TableOfContents(3)>>
Line 10: Line 9:
== Types == == Quick overview ==

This provides a scrollable view. The content is a rectangle, and the viewport is a rectangle whose area is a subset of the content. The content and viewport can be thought of as boxes. The viewport may be dragged within the content.

While the user is interacting with the viewport by scrolling on an input device, the viewport follows the scroll motion. When the scrolling ceases, the viewport will continue moving. As it moves, friction will slow it down until it finally stops.

When the viewport hits the edge of the area, something happens. By default all motion of the viewport is stopped. The library may provide alternative behaviour, such as "bouncing", sliding along the edge and so on.

== User stories ==

The physics library should do following:

 * provide a viewport that can be scrolled and which slows down according to physical laws
 * provide several different behaviours when the area hits the edge: stopping, bouncing like Android's list widget etc
 * support setting friction and other such variables
 * provide (possibly system global) default values for the above
 * allow changing the scrolling speed and direction even if there is a scroll event ongoing
 * the physical simulation is not tied to the system clock
 * the source of motion can be a touch gesture, mouse flick, accelerometer, or any other device capable of providing velocity information

Functionality it will not have:

 * it does not convert coordinate types (e.g. from touchpad device coordinates to pixels), it will only work in pixel units
 * it does not support on-the-fly area or viewport resizing because the "correct" behaviour is strongly application dependent
 * it is not thread-safe

== Using the library ==

'''Note''': the code samples in this section are descriptive. They may not line up exactly with the API described further in this document.

=== Creating a scroller ===

{{{
scroller = new_scroller(area_width, area_height, viewport_width, viewport_height);
}}}

=== Starting scroll motion ===

{{{
set_viewport_location(scroller, new_x, new_y);
set_velocity(scroller, vx, vy);
}}}

=== Updating the scroll ===

The update is modeled after {{{glib}}}'s {{{g_timeout_add}}} functionality. The scroller is told to advance forward some amount of time. It calculates its new location and returns false if the viewport has stopped and true if motion is still ongoing.

{{{
long now_time = get_time();
long delta_t = now_time - previous_time;
bool motion_remaining;

motion_remaining = scroller_step_forward_in_time(scroller, delta_t);
previous_time = now_time;
redraw_canvas_and_other_such_things();
if(motion_remaining)
  more_to_come();
else
  motion_has_finished();
}}}

=== Shutting down the scroller ===

{{{
scroller_delete(scroller);
}}}

----

''Old content starts here.''

== API Types ==
Line 12: Line 82:
Handle for uTouch-Physics context Handle for uTouch-Physics context.

=== uphys_model ===
Enum specifying the model of the uphys context.

Values:
 * UPHYS_SCROLLVIEW

=== 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.
Line 15: Line 104:
=== gravity === === 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 ===
Line 18: Line 117:
=== 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''.

=== simulation_step_size: float ===
Simulation step size in ms. Defaults to ''TBD'' (maybe 30 Hz).

See [[http://gafferongames.com/game-physics/fix-your-timestep/|here]] for more info.

=== (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.
Line 19: Line 147:
=== uphys *uphys_new_scrollview() ===
Create a new uphys context.

Returns a new context or NULL on error.
Line 33: Line 156:

=== 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(uphys_model model) ===
Create a new uphys context for a the model.

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(UPHYS_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<<BR>>
  - 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<<BR>>
  - 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

Library: uTouch-Physics
Language: C (Maybe built on top of GLib? Qt already depends on GLib by default if available.)
Dependencies: possibly a physics engine such as Chipmunk

Note: This page is in the process of being rewritten. It will be inconsistent until this task is finished.

Contents

  1. Quick overview
  2. User stories
  3. Using the library
    1. Creating a scroller
    2. Starting scroll motion
    3. Updating the scroll
    4. Shutting down the scroller
  4. API Types
    1. uphys
    2. uphys_model
    3. uphys_units
    4. uphys_point
    5. uphys_size
  5. uphys Properties
    1. error: int
    2. error_string: const char *
    3. gravity: float
    4. mm_multiplier: float
    5. mu: float
    6. simulation_step_size: float
    7. (scrollview) viewport_origin: uphys_point
    8. (scrollview) viewport_size: uphys_size
    9. (scrollview) content_origin: uphys_point
    10. (scrollview) content_size: uphys_size
  6. Functions
    1. int uphys_set_property(uphys *uphys, const char *name, void *value)
    2. int uphys_get_property(const uphys *uphys, const char *name, void *value)
    3. void uphys_inject(uphys *uphys, GeisEvent event)
    4. void uphys_update(uphys *uphys, time_t *time)
    5. uphys *uphys_new(uphys_model model)
  7. API Use Case Example

Quick overview

This provides a scrollable view. The content is a rectangle, and the viewport is a rectangle whose area is a subset of the content. The content and viewport can be thought of as boxes. The viewport may be dragged within the content.

While the user is interacting with the viewport by scrolling on an input device, the viewport follows the scroll motion. When the scrolling ceases, the viewport will continue moving. As it moves, friction will slow it down until it finally stops.

When the viewport hits the edge of the area, something happens. By default all motion of the viewport is stopped. The library may provide alternative behaviour, such as "bouncing", sliding along the edge and so on.

User stories

The physics library should do following:

  • provide a viewport that can be scrolled and which slows down according to physical laws
  • provide several different behaviours when the area hits the edge: stopping, bouncing like Android's list widget etc
  • support setting friction and other such variables
  • provide (possibly system global) default values for the above
  • allow changing the scrolling speed and direction even if there is a scroll event ongoing
  • the physical simulation is not tied to the system clock
  • the source of motion can be a touch gesture, mouse flick, accelerometer, or any other device capable of providing velocity information

Functionality it will not have:

  • it does not convert coordinate types (e.g. from touchpad device coordinates to pixels), it will only work in pixel units
  • it does not support on-the-fly area or viewport resizing because the "correct" behaviour is strongly application dependent
  • it is not thread-safe

Using the library

Note: the code samples in this section are descriptive. They may not line up exactly with the API described further in this document.

Creating a scroller

scroller = new_scroller(area_width, area_height, viewport_width, viewport_height);

Starting scroll motion

set_viewport_location(scroller, new_x, new_y);
set_velocity(scroller, vx, vy);

Updating the scroll

The update is modeled after glib's g_timeout_add functionality. The scroller is told to advance forward some amount of time. It calculates its new location and returns false if the viewport has stopped and true if motion is still ongoing. 

long now_time = get_time();
long delta_t = now_time - previous_time;
bool motion_remaining;

motion_remaining = scroller_step_forward_in_time(scroller, delta_t);
previous_time = now_time;
redraw_canvas_and_other_such_things();
if(motion_remaining)
  more_to_come();
else
  motion_has_finished();

Shutting down the scroller

scroller_delete(scroller);

Old content starts here.

API Types

uphys

Handle for uTouch-Physics context.

uphys_model

Enum specifying the model of the uphys context.

Values:

  • UPHYS_SCROLLVIEW

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/s2. This is calculated by multiplying the standard earth gravity of 9.8 m/s2 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.

simulation_step_size: float

Simulation step size in ms. Defaults to TBD (maybe 30 Hz).

See here for more info.

(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(uphys_model model)

Create a new uphys context for a the model.

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(UPHYS_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

Multitouch/Physics (last edited 2012-06-14 19:28:34 by c-67-170-185-42)