frame.h   frame.h 
/************************************************************************** *** /************************************************************************** ***
* *
* utouch-frame - Touch Frame Library * frame - Touch Frame Library
* *
* Copyright (C) 2010-2012 Canonical Ltd. * Copyright (C) 2010-2012 Canonical Ltd.
* *
* This library is free software: you can redistribute it and/or modify it * This library is free software: you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License version 3 * under the terms of the GNU Lesser General Public License version 3
* as published by the Free Software Foundation. * as published by the Free Software Foundation.
* *
* This library is distributed in the hope that it will be useful, but * This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranties of * WITHOUT ANY WARRANTY; without even the implied warranties of
* MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU Lesser General Public License for more details. * PURPOSE. See the GNU Lesser General Public License for more details.
* *
* You should have received a copy of the GNU Lesser General Public License * You should have received a copy of the GNU Lesser General Public License
* along with this library. If not, see <http://www.gnu.org/licenses/>. * along with this library. If not, see <http://www.gnu.org/licenses/>.
* *
************************************************************************** **/ ************************************************************************** **/
/** /**
* @file utouch/frame.h * @file oif/frame.h
* Definitions of the main and platform-generic API * Definitions of the main and platform-generic API
*/ */
#ifndef UTOUCH_FRAME_UTOUCH_FRAME_H_ #ifndef FRAME_OIF_FRAME_H_
#define UTOUCH_FRAME_UTOUCH_FRAME_H_ #define FRAME_OIF_FRAME_H_
/* Macros that set symbol visibilities in shared libraries properly. /* Macros that set symbol visibilities in shared libraries properly.
* Adapted from http://gcc.gnu.org/wiki/Visibility * Adapted from http://gcc.gnu.org/wiki/Visibility
*/ */
#if defined _WIN32 || defined __CYGWIN__ #if defined _WIN32 || defined __CYGWIN__
#ifdef BUILDING_FRAME #ifdef BUILDING_FRAME
#define FRAME_PUBLIC __declspec(dllexport) #define FRAME_PUBLIC __declspec(dllexport)
#else #else
#define FRAME_PUBLIC __declspec(dllimport) #define FRAME_PUBLIC __declspec(dllimport)
#endif #endif
#else #else
#if defined __GNUC__ #if defined __GNUC__
#define FRAME_PUBLIC __attribute__ ((visibility("default"))) #define FRAME_PUBLIC __attribute__ ((visibility("default")))
#else #else
#pragma message ("Compiler does not support symbol visibility.") #pragma message ("Compiler does not support symbol visibility.")
#define FRAME_PUBLIC #define FRAME_PUBLIC
#endif #endif
#endif #endif
/* Clang provides __has_extension, but GCC does not */ /* Clang provides __has_feature, but GCC does not */
#ifdef __has_extension #ifdef __has_feature
#if __has_extension(c_generic_selections) #if __has_feature(c_generic_selections)
#define HAS_C_GENERIC_SELECTIONS #define HAS_C_GENERIC_SELECTIONS
#endif // __has_extension #endif // __has_feature
#endif // __has_extension(c_generic_selections) #endif // __has_feature(c_generic_selections)
/* Whether the X11 backend (frame_x11.h) is available.
FRAME_X11_BACKEND will be defined if it is and FRAME_NO_X11_BACKEND othe
rwise. */
#define FRAME_NO_X11_BACKEND
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#include <stdint.h> #include <stdint.h>
/** /** An object for the context of the frame instance */
* @defgroup v1 uTouch-Frame 1.x
* @{
* @internal
*/
#define UTOUCH_FRAME_VERSION 0x00001010
/**
* struct utouch_surface - device surface details
* @needs_pointer: device needs a screen pointer to function
* @is_direct: surface is a direct device (e.g. touchscreen)
* @is_buttonpad: surface has button(s) under it
* @is_semi_mt: surface detects bounding rectangle only
* @use_touch_major: device uses major axis for contact modulation
* @use_touch_minor: device uses minor axis for contact modulation
* @use_width_major: device uses approaching major axis for contact modulat
ion
* @use_width_minor: device uses approaching minor axis for contact modulat
ion
* @use_orientation: device uses ellipse orientation for contact modulation
* @use_pressure: device uses pressure for contact modulation
* @use_distance: device uses hover distance
* @phys_width: physical width in millimeters (mm)
* @phys_height: physical height in millimeters (mm)
* @phys_pressure: maximal physical pressure (N/cm^2)
* @min_x: minimum horizontal device coordinate
* @min_y: minimum vertical device coordinate
* @max_x: maximum horizontal device coordinate
* @max_y: maximum vertical device coordinate
* @max_pressure: maximum pressure device coordinate
* @max_orient: maximum orientation device coordinate
* @mapped_min_x: minimum horizontal mapped coordinate
* @mapped_min_y: minimum vertical mapped coordinate
* @mapped_max_x: maximum horizontal mapped coordinate
* @mapped_max_y: maximum vertical mapped coordinate
* @mapped_max_pressure: maximum pressure mapped coordinate
*
* The mutable contact given by utouch_frame_get_current_slot() should
* be set in device coordinates. The contact data is subsequently
* transformed to mapped (e.g., screen) coordinates in
* utouch_frame_sync(). To a frame user, all data will appear in
* mapped coordinates.
*
* Device properties and touch surface details. Later versions of this
* struct may grow in size, but will remain binary compatible with
* older versions.
*/
struct utouch_surface {
int needs_pointer;
int is_direct;
int is_buttonpad;
int is_semi_mt;
int use_touch_major;
int use_touch_minor;
int use_width_major;
int use_width_minor;
int use_orientation;
int use_pressure;
int use_distance;
float phys_width;
float phys_height;
float phys_pressure;
float min_x;
float min_y;
float max_x;
float max_y;
float max_pressure;
float max_orient;
float mapped_min_x;
float mapped_min_y;
float mapped_max_x;
float mapped_max_y;
float mapped_max_pressure;
unsigned int min_id;
unsigned int max_id;
};
#define UTOUCH_TOOL_FINGER 0
#define UTOUCH_TOOL_PEN 1
/**
* struct utouch_contact - surface contact details
* @prev: pointer to same slot of previous frame
* @active: currently in use
* @slot: slot occupied by this contact
* @id: unique id of this contact
* @tool_type: the tool type of this contact
* @x: horizontal center position coordinate (surface units)
* @y: vertical center position coordinate (surface units)
* @touch_major: major axis of contact (surface units)
* @touch_minor: minor axis of contact (surface units)
* @width_major: major axis of approaching contact (surface units)
* @width_minor: minor axis of approaching contact (surface units)
* @orientation: direction of ellipse (left: -Pi/2, up: 0, right: Pi/2)
* @pressure: pressure of contact (pressure units)
* @distance: distance of contact (surface units)
* @vx: horizontal velocity coordinate (units / millisecond)
* @vy: vertical velocity coordinate (units / millisecond)
*
* Surface contact details. Later versions of this struct may grow in
* size, but will remain binary compatible with older versions.
*
* Contact structures are connected into one ring per slot. The
* previous contact pointers are ABI agnostic, owned by the engine,
* and have engine scope.
*/
struct utouch_contact {
const struct utouch_contact *prev;
int active;
int slot;
unsigned int id;
int tool_type;
float x;
float y;
float touch_major;
float touch_minor;
float width_major;
float width_minor;
float orientation;
float pressure;
float distance;
float vx;
float vy;
};
/* time in milliseconds */
typedef uint64_t utouch_frame_time_t;
/* the frame engine handle */
typedef struct utouch_frame_engine *utouch_frame_handle;
/**
* struct utouch_frame - emitted frame details
* @prev: pointer to previous frame
* @sequence_id: frame sequence number
* @revision: changes whenever the contact count changes
* @slot_revision: changes whenever the slot id array change
* @num_active: the number of contacts in the active array
* @time: time of frame completion (ms)
* @mod_time: time of last contact count change (ms)
* @slot_mod_time: time of last slot id array change (ms)
* @active: the array of active contacts
*
* Contact frame details. Later versions of this struct may grow in
* size, but will remain binary compatible with older versions.
*
* Frames are connected into a ring. The previous frame pointer is ABI
* agnostic, owned by the engine, and has engine scope.
*/
struct utouch_frame {
const struct utouch_frame *prev;
unsigned int sequence_id;
unsigned int revision;
unsigned int slot_revision;
unsigned int num_active;
utouch_frame_time_t time;
utouch_frame_time_t mod_time;
utouch_frame_time_t slot_mod_time;
struct utouch_contact **active;
struct utouch_contact **slots;
};
/**
* utouch_frame_get_version - get library abi version
*
* Returns the version of the library, which may be different
* from the api version of the compiled user program.
*/
FRAME_PUBLIC
unsigned int utouch_frame_get_version(void);
/**
* utouch_frame_get_num_frames - get number of supported frames
*
* Returns the number of frames supported by this engine.
*/
FRAME_PUBLIC
unsigned int utouch_frame_get_num_frames(utouch_frame_handle fh);
/**
* utouch_frame_get_num_slots - get number of supported slots
*
* Returns the number of simultaneous contacts supported by this engine.
*/
FRAME_PUBLIC
unsigned int utouch_frame_get_num_slots(utouch_frame_handle fh);
FRAME_PUBLIC
utouch_frame_handle utouch_frame_new_engine_raw(unsigned int num_frames,
unsigned int num_slots,
unsigned int frame_rate,
unsigned int version,
unsigned int surface_size,
unsigned int frame_size,
unsigned int slot_size);
/**
* utouch_frame_new_engine - allocate a new frame engine
* @num_frames: number of frames in cyclic buffer
* @num_slots: maximum number of slots per frame
* @frame_rate: maximum frame rate (frames/s)
*
* Allocates memory, initializes the internal engine and returns a
* handle to it. A rate of 100 frames per second is normal.
*/
#define utouch_frame_new_engine(num_frames, num_slots, frame_rate) \
utouch_frame_new_engine_raw(num_frames, \
num_slots, \
frame_rate, \
UTOUCH_FRAME_VERSION, \
sizeof(struct utouch_surface), \
sizeof(struct utouch_frame), \
sizeof(struct utouch_contact))
/**
* utouch_frame_delete_engine - deallocate a frame engine
* @fh: frame engine in use
*
* Deallocates all memory associated with the engine.
*/
FRAME_PUBLIC
void utouch_frame_delete_engine(utouch_frame_handle fh);
/**
* utouch_frame_get_surface - get the mutable device surface information
* @fh: the frame engine in use
*
* Returns a pointer to the mutable device surface information. It is
* preferrably set up by one of the input handlers. The pointer is ABI
* agnostic, has frame engine scope, and is owned by the engine.
*/
FRAME_PUBLIC
struct utouch_surface *utouch_frame_get_surface(utouch_frame_handle fh);
/**
* utouch_frame_get_current_slot - get the current mutable slot contact
* @fh: the frame engine in use
*
* Returns a pointer to the contact current being modified. The
* pointer is ABI agnostic, has frame engine scope, and is owned by
* the engine.
*/
FRAME_PUBLIC
struct utouch_contact *utouch_frame_get_current_slot(utouch_frame_handle fh
);
/**
* utouch_frame_set_current_slot - set the current slot number
* @fh: the frame engine in use
* @slot: the slot number
*
* Sets the slot currently being modified. Returns zero if successful,
* negative error otherwise.
*/
FRAME_PUBLIC
int utouch_frame_set_current_slot(utouch_frame_handle fh, int slot);
/**
* utouch_frame_set_current_id - set the current slot by touch id
* @fh: the frame engine in use
* @id: the touch id
*
* Sets the slot currently being modified, by touch id. If the id is
* not currently in use (does not have an active slot), a new slot is
* assigned. Returns zero if successful, negative error otherwise.
*/
FRAME_PUBLIC
int utouch_frame_set_current_id(utouch_frame_handle fh, int id);
/**
* utouch_frame_sync - synchronize and return new frame
* @fh: the frame engine in use
* @time: the frame synchronization time (ms)
*
* Scans through the updates, and in case the changes make up a new
* frame, returns the updated frame.
*
* If time is zero, a time-of-receipt will be used instead.
*
* The frame returned is always the next in the cyclic list, and
* always points back at the previous frame returned by this function.
*
* The returned pointer is ABI agnostic and owned by the frame
* engine. It may very well be zero if there is nothing to report or
* if the frame rate is limited.
*/
FRAME_PUBLIC
const struct utouch_frame *utouch_frame_sync(utouch_frame_handle fh,
utouch_frame_time_t time);
/**
* utouch_coordinate_transform_cb - user-definable callback that transforms
a touch point
* @x: pointer to an x coordinate (in, out)
* @y: pointer to a y coordinate (in, out)
* @user_data: opaque pointer, passed by the user when setting the callback
*/
typedef void (*utouch_coordinate_transform_cb)(float *x, float *y, void *us
er_data);
/**
* utouch_frame_set_coordinate_transform_callback - set a callback to obtai
n a transformation
* to apply to every touch point
* @fh: the frame engine in use
* @callback: the callback that transforms x and y
* @user_data: opaque pointer to user data for the callback
*/
FRAME_PUBLIC
void utouch_frame_set_coordinate_transform_callback(utouch_frame_handle fh,
utouch_coordinate_transf
orm_cb callback,
void *user_data);
/** @} */
/**
* @defgroup v2 uTouch-Frame 2.x
* @{
*/
/** An object for the context of the uTouch Frame instance */
typedef struct UFHandle_* UFHandle; typedef struct UFHandle_* UFHandle;
/** An object for an event */ /** An object for an event */
typedef struct UFEvent_* UFEvent; typedef struct UFEvent_* UFEvent;
/** An object for a frame of touches */ /** An object for a frame of touches */
typedef struct UFFrame_* UFFrame; typedef struct UFFrame_* UFFrame;
/** An object for a touch */ /** An object for a touch */
typedef struct UFTouch_* UFTouch; typedef struct UFTouch_* UFTouch;
/** An object for a device */ /** An object for a device */
typedef struct UFDevice_* UFDevice; typedef struct UFDevice_* UFDevice;
/** An object for a device axis */ /** An object for a device axis */
skipping to change at line 406 skipping to change at line 96
UFStatusErrorResources, /**< An error occurred due to insufficient resour ces */ UFStatusErrorResources, /**< An error occurred due to insufficient resour ces */
UFStatusErrorNoEvent, /**< No events were available to get */ UFStatusErrorNoEvent, /**< No events were available to get */
UFStatusErrorUnknownProperty, /**< The requested property value was not s et */ UFStatusErrorUnknownProperty, /**< The requested property value was not s et */
UFStatusErrorInvalidTouch, /**< The requested touch does not exist */ UFStatusErrorInvalidTouch, /**< The requested touch does not exist */
UFStatusErrorInvalidAxis, /**< The requested axis does not exist */ UFStatusErrorInvalidAxis, /**< The requested axis does not exist */
UFStatusErrorUnsupported, /**< The requested function is not supported by the UFStatusErrorUnsupported, /**< The requested function is not supported by the
window server */ window server */
UFStatusErrorInvalidType, /**< The variable type passed as a void pointer into UFStatusErrorInvalidType, /**< The variable type passed as a void pointer into
a property getter is invalid for the prope rty a property getter is invalid for the prope rty
*/ */
UFStatusErrorTouchIdExists, /**< A touch with the same ID already exists */
} UFStatus; } UFStatus;
/** Properties of a device */ /** Properties of a device */
typedef enum UFDeviceProperty { typedef enum UFDeviceProperty {
/** /**
* The name of the device * The name of the device
* *
* Value type: const char * * Value type: const char *
* *
* The uTouch frame library owns the string. The string is valid until an * The frame library owns the string. The string is valid until an event
* event notifying removal of the device is released. * notifying removal of the device is released.
*/ */
UFDevicePropertyName = 0, UFDevicePropertyName = 0,
/** /**
* Whether the device is a direct touch device * Whether the device is a direct touch device
* *
* Value type: int with boolean semantics * Value type: int with boolean semantics
* *
* A direct touch device is a device where there is a direct transformati on * A direct touch device is a device where there is a direct transformati on
* from the touch location to the event location on the screen. An indire ct * from the touch location to the event location on the screen. An indire ct
* touch device is a device where the touch has meaning relative to a pos ition * touch device is a device where the touch has meaning relative to a pos ition
skipping to change at line 533 skipping to change at line 224
* object is owned by the library and is valid until the event is release d. * object is owned by the library and is valid until the event is release d.
*/ */
UFEventPropertyFrame, UFEventPropertyFrame,
/** /**
* Event time * Event time
* *
* Value type: 64-bit unsigned int * Value type: 64-bit unsigned int
* *
* This property holds the time the event occurred in display server * This property holds the time the event occurred in display server
* timespace. The time is provided in milliseconds (ms). If the event, su ch as * timespace. The time is provided in milliseconds (ms). If the event, su ch as
* device addition, occurred before the uTouch Frame context was created, * device addition, occurred before the frame context was created, the va
the lue
* value will be 0. * will be 0.
*/ */
UFEventPropertyTime, UFEventPropertyTime,
} UFEventProperty; } UFEventProperty;
/** Event types */ /** Event types */
typedef enum UFEventType { typedef enum UFEventType {
UFEventTypeDeviceAdded = 0, /**< A new device has been added */ UFEventTypeDeviceAdded = 0, /**< A new device has been added */
UFEventTypeDeviceRemoved, /**< An existing device has been removed */ UFEventTypeDeviceRemoved, /**< An existing device has been removed */
UFEventTypeFrame, /**< The state of one or more touches has changed */ UFEventTypeFrame, /**< The state of one or more touches has changed */
} UFEventType; } UFEventType;
skipping to change at line 660 skipping to change at line 351
* *
* Some window servers have the concept of touch ownership. If a touch ha s * Some window servers have the concept of touch ownership. If a touch ha s
* ended before the client receives ownership, this property will be set to * ended before the client receives ownership, this property will be set to
* true. The property will also be set to true when the touch has ended b efore * true. The property will also be set to true when the touch has ended b efore
* the client has accepted or rejected ownership of the touch sequence. * the client has accepted or rejected ownership of the touch sequence.
*/ */
UFTouchPropertyPendingEnd, UFTouchPropertyPendingEnd,
} UFTouchProperty; } UFTouchProperty;
/** /**
* Get the event file descriptor for the uTouch Frame context * Get the event file descriptor for the frame context
* *
* @param [in] handle The uTouch Frame context object * @param [in] handle The frame context object
* @return A file descriptor for the context * @return A file descriptor for the context
* *
* When events are available for processing, the file descriptor will be * When events are available for processing, the file descriptor will be
* readable. Perform an 8-byte read from the file descriptor to clear the s tate. * readable. Perform an 8-byte read from the file descriptor to clear the s tate.
* Refer to the EVENTFD(2) man page for more details. * Refer to the EVENTFD(2) man page for more details.
*/ */
FRAME_PUBLIC FRAME_PUBLIC
int frame_get_fd(UFHandle handle); int frame_get_fd(UFHandle handle);
/** /**
* Get an event from the uTouch Frame context * Get an event from the frame context
* *
* @param [in] handle The context object * @param [in] handle The context object
* @param [out] event The retrieved event * @param [out] event The retrieved event
* @return UFStatusSuccess or UFStatusErrorNoEvent * @return UFStatusSuccess or UFStatusErrorNoEvent
* *
* The reference count of the returned event is implicity incremented once. * The reference count of the returned event is implicity incremented once.
*/ */
FRAME_PUBLIC FRAME_PUBLIC
UFStatus frame_get_event(UFHandle handle, UFEvent *event); UFStatus frame_get_event(UFHandle handle, UFEvent *event);
skipping to change at line 1055 skipping to change at line 746
* Get the start time of a touch * Get the start time of a touch
* *
* @param [in] touch The touch object (const) * @param [in] touch The touch object (const)
* @return The start time of the touch * @return The start time of the touch
*/ */
FRAME_PUBLIC FRAME_PUBLIC
uint64_t frame_touch_get_start_time(UFTouch touch); uint64_t frame_touch_get_start_time(UFTouch touch);
/** @} */ /** @} */
/** @} */ #include "frame_internal.h"
#include <utouch/frame_internal.h>
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#undef HAS_C_GENERIC_SELECTIONS #undef HAS_C_GENERIC_SELECTIONS
#endif // UTOUCH_FRAME_UTOUCH_FRAME_H_ #endif // FRAME_OIF_FRAME_H_
 End of changes. 14 change blocks. 
342 lines changed or deleted 25 lines changed or added


 frame_internal.h   frame_internal.h 
/************************************************************************** *** /************************************************************************** ***
* *
* utouch-frame - Touch Frame Library * frame - Touch Frame Library
* *
* Copyright (C) 2010-2012 Canonical Ltd. * Copyright (C) 2010-2012 Canonical Ltd.
* *
* This library is free software: you can redistribute it and/or modify it * This library is free software: you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License version 3 * under the terms of the GNU Lesser General Public License version 3
* as published by the Free Software Foundation. * as published by the Free Software Foundation.
* *
* This library is distributed in the hope that it will be useful, but * This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranties of * WITHOUT ANY WARRANTY; without even the implied warranties of
* MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU Lesser General Public License for more details. * PURPOSE. See the GNU Lesser General Public License for more details.
* *
* You should have received a copy of the GNU Lesser General Public License * You should have received a copy of the GNU Lesser General Public License
* along with this library. If not, see <http://www.gnu.org/licenses/>. * along with this library. If not, see <http://www.gnu.org/licenses/>.
* *
************************************************************************** **/ ************************************************************************** **/
#ifndef UTOUCH_FRAME_UTOUCH_FRAME_INTERNAL_H_ #ifndef FRAME_OIF_FRAME_INTERNAL_H_
#define UTOUCH_FRAME_UTOUCH_FRAME_INTERNAL_H_ #define FRAME_OIF_FRAME_INTERNAL_H_
#ifdef HAS_C_GENERIC_SELECTIONS #ifdef HAS_C_GENERIC_SELECTIONS
#include <stdint.h> #include <stdint.h>
FRAME_PUBLIC FRAME_PUBLIC
UFStatus frame_device_get_property_string_(UFDevice device, UFStatus frame_device_get_property_string_(UFDevice device,
UFDeviceProperty property, UFDeviceProperty property,
char **value); char **value);
FRAME_PUBLIC FRAME_PUBLIC
skipping to change at line 120 skipping to change at line 120
#define frame_touch_get_property(touch, property, value) \ #define frame_touch_get_property(touch, property, value) \
_Generic((value), \ _Generic((value), \
uint64_t *: frame_touch_get_property_uint64_, \ uint64_t *: frame_touch_get_property_uint64_, \
UFTouchState *: frame_touch_get_property_state_, \ UFTouchState *: frame_touch_get_property_state_, \
float *: frame_touch_get_property_float_, \ float *: frame_touch_get_property_float_, \
int *: frame_touch_get_property_int_) ((touch), (property), \ int *: frame_touch_get_property_int_) ((touch), (property), \
(value)) (value))
#endif // HAS_C_GENERIC_SELECTIONS #endif // HAS_C_GENERIC_SELECTIONS
#endif // UTOUCH_FRAME_UTOUCH_FRAME_INTERNAL_H_ #endif // FRAME_OIF_FRAME_INTERNAL_H_
 End of changes. 3 change blocks. 
3 lines changed or deleted 3 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/