« back to all changes in this revision
Viewing changes to include/utouch/frame.h
- browse files at revision 40
- compare with another revision
- download diff
- download tarball
- view history from revision 40
- Committer: Chase Douglas
- Date: 2011-12-09 01:36:45 UTC
- mfrom: (1.1.7 upstream)
- Revision ID: chase.douglas@ubuntu.com-20111209013645-n24l4myiumblzsfu
* New upstream release.
- Version 2 adds a new API built on top of XInput multitouch
- Version 2 adds a new API built on top of XInput multitouch
- files added:
- doc
- m4
- src/v1
- src/v2
- src/v2/x11
- test/recordings
- test/x11
- tools/common
- files renamed:
- src/frame-impl.h => src/v1/frame-impl.h
- src/frame-mtdev.c => src/v1/frame-mtdev.c
- src/frame-xi2.c => src/v1/frame-xi2.c
- src/frame.c => src/v1/frame.c
- files modified:
- ChangeLog
added
removed
include/utouch/frame.h
19
19
*
20
20
****************************************************************************/
21
21
22
#ifndef UTOUCH_FRAME_H
23
#define UTOUCH_FRAME_H
22
/**
23
* @file utouch/frame.h
24
* Definitions of the main and platform-generic API
25
*/
26
27
#ifndef UTOUCH_FRAME_UTOUCH_FRAME_H_
28
#define UTOUCH_FRAME_UTOUCH_FRAME_H_
24
29
25
30
#ifdef __cplusplus
26
31
extern "C" {
28
33
29
34
#include <stdint.h>
30
35
36
/**
37
* @defgroup v1 uTouch-Frame 1.x
38
* @{
39
* @internal
40
*/
41
31
42
#define UTOUCH_FRAME_VERSION 0x00001010
32
43
33
44
/**
300
311
const struct utouch_frame *utouch_frame_sync(utouch_frame_handle fh,
301
312
utouch_frame_time_t time);
302
313
314
/**
315
* utouch_coordinate_transform_cb - user-definable callback that transforms a touch point
316
* @x: pointer to an x coordinate (in, out)
317
* @y: pointer to a y coordinate (in, out)
318
* @user_data: opaque pointer, passed by the user when setting the callback
319
*/
320
typedef void (*utouch_coordinate_transform_cb)(float *x, float *y, void *user_data);
321
322
/**
323
* utouch_frame_set_coordinate_transform_callback - set a callback to obtain a transformation
324
* to apply to every touch point
325
* @fh: the frame engine in use
326
* @callback: the callback that transforms x and y
327
* @user_data: opaque pointer to user data for the callback
328
*/
329
void utouch_frame_set_coordinate_transform_callback(utouch_frame_handle fh,
330
utouch_coordinate_transform_cb callback,
331
void *user_data);
332
/** @} */
333
334
/**
335
* @defgroup v2 uTouch-Frame 2.x
336
* @{
337
*/
338
339
/** An object for the context of the uTouch Frame instance */
340
typedef struct UFHandle_* UFHandle;
341
/** An object for an event */
342
typedef struct UFEvent_* UFEvent;
343
/** An object for a frame of touches */
344
typedef struct UFFrame_* UFFrame;
345
/** An object for a touch */
346
typedef struct UFTouch_* UFTouch;
347
/** An object for a device */
348
typedef struct UFDevice_* UFDevice;
349
/** An object for a device axis */
350
typedef struct UFAxis_* UFAxis;
351
/** An object for a window ID */
352
typedef uint64_t UFWindowId;
353
/** An object for a touch ID */
354
typedef uint64_t UFTouchId;
355
356
/** The status code denoting the result of a function call */
357
typedef enum UFStatus {
358
UFStatusSuccess = 0, /**< The call was successful */
359
UFStatusErrorGeneric, /**< A platform-dependent error occurred */
360
UFStatusErrorResources, /**< An error occurred due to insufficient resources */
361
UFStatusErrorNoEvent, /**< No events were available to get */
362
UFStatusErrorUnknownProperty, /**< The requested property value was not set */
363
UFStatusErrorInvalidTouch, /**< The requested touch does not exist */
364
UFStatusErrorInvalidAxis, /**< The requested axis does not exist */
365
UFStatusErrorUnsupported, /**< The requested function is not supported by the
366
window server */
367
} UFStatus;
368
369
/** Properties of a device */
370
typedef enum UFDeviceProperty {
371
/**
372
* The name of the device
373
*
374
* Value type: const char *
375
*
376
* The uTouch frame library owns the string. The string is valid until an
377
* event notifying removal of the device is released.
378
*/
379
UFDevicePropertyName = 0,
380
/**
381
* Whether the device is a direct touch device
382
*
383
* Value type: int with boolean semantics
384
*
385
* A direct touch device is a device where there is a direct transformation
386
* from the touch location to the event location on the screen. An indirect
387
* touch device is a device where the touch has meaning relative to a position
388
* on the screen, such as the location of a cursor. A touchscreens is an
389
* example of a direct device, and a trackpad is an example of an indirect
390
* device.
391
*/
392
UFDevicePropertyDirect,
393
/**
394
* Whether the device is an independent touch device
395
*
396
* Value type: int with boolean semantics
397
*
398
* An independent device is an indirect device whose cursor moves
399
* independently of the touches on the device. A mouse with a touch area for
400
* gestures is an example of an independent device, and a trackpad is an
401
* example of a dependent device.
402
*/
403
UFDevicePropertyIndependent,
404
/**
405
* Whether the device is a semi-multitouch device
406
*
407
* Value type: int with boolean semantics
408
*
409
* A semi-multitouch device provides a bounding box of some touches on the
410
* touch surface. In contrast, a full-multitouch device provides accurate
411
* locations of each individual touch.
412
*/
413
UFDevicePropertySemiMT,
414
/**
415
* The maximum number of touches supported by the device
416
*
417
* Value type: unsigned int
418
*/
419
UFDevicePropertyMaxTouches,
420
/**
421
* The number of touch axes provided by the device
422
*
423
* Value type: unsigned int
424
*/
425
UFDevicePropertyNumAxes,
426
} UFDeviceProperty;
427
428
/** Device touch axis types */
429
typedef enum UFAxisType {
430
UFAxisTypeX = 0, /**< X coordinate */
431
UFAxisTypeY, /**< Y coordinate */
432
UFAxisTypeTouchMajor, /**< Width along major axis of contact area of touch */
433
UFAxisTypeTouchMinor, /**< Width along minor axis of contact area of touch */
434
UFAxisTypeWidthMajor, /**< Width along major axis of touch tool */
435
UFAxisTypeWidthMinor, /**< Width along minor axis of touch tool */
436
UFAxisTypeOrientation, /**< Orientation of major axis of contact ellipse */
437
UFAxisTypeTool, /**< Tool type */
438
UFAxisTypeBlobId, /**< Blob ID of group of touches */
439
UFAxisTypeTrackingId, /**< Tracking ID */
440
UFAxisTypePressure, /**< Pressure */
441
UFAxisTypeDistance, /**< Hover distance */
442
} UFAxisType;
443
444
/** Event properties */
445
typedef enum UFEventProperty {
446
/**
447
* Type of event
448
*
449
* Value type: UFEventType
450
*/
451
UFEventPropertyType = 0,
452
/**
453
* Device added or removed
454
*
455
* Value type: UFDevice
456
*
457
* This property is set only when the event type is UFEventTypeDeviceAdded
458
* or UFEventTypeDeviceRemoved. The object is owned by the library and is
459
* valid until an event notifying removal of the device is released.
460
*/
461
UFEventPropertyDevice,
462
/**
463
* Touch frame
464
*
465
* Value type: UFFrame
466
*
467
* This property is set only when the event type is UFEventTypeFrame. The
468
* object is owned by the library and is valid until the event is released.
469
*/
470
UFEventPropertyFrame,
471
/**
472
* Event time
473
*
474
* Value type: 64-bit unsigned int
475
*
476
* This property holds the time the event occurred in display server
477
* timespace. The time is provided in milliseconds (ms). If the event, such as
478
* device addition, occurred before the uTouch Frame context was created, the
479
* value will be 0.
480
*/
481
UFEventPropertyTime,
482
} UFEventProperty;
483
484
/** Event types */
485
typedef enum UFEventType {
486
UFEventTypeDeviceAdded = 0, /**< A new device has been added */
487
UFEventTypeDeviceRemoved, /**< An existing device has been removed */
488
UFEventTypeFrame, /**< The state of one or more touches has changed */
489
} UFEventType;
490
491
/** Touch frame properties */
492
typedef enum UFFrameProperty {
493
/**
494
* The device for the frame
495
*
496
* Value type: UFDevice
497
*/
498
UFFramePropertyDevice = 0,
499
/**
500
* The window server ID of the window for the frame
501
*
502
* Value type: UFWindowId
503
*/
504
UFFramePropertyWindowId,
505
/**
506
* Number of touches in the frame
507
*
508
* Value type: unsigned int
509
*
510
* Some devices can track more touches than they can report data for. Only
511
* touches with X and Y position are provided in the frame.
512
*/
513
UFFramePropertyNumTouches,
514
/**
515
* Total number of active touches on the device
516
*
517
* Value type: unsigned int
518
*
519
* Some devices can track more touches than they can report data for. This
520
* value includes the number of reported and unreported touches.
521
*/
522
UFFramePropertyActiveTouches,
523
} UFFrameProperty;
524
525
/** State of an individual touch */
526
typedef enum UFTouchState {
527
UFTouchStateBegin = 0, /**< The touch began */
528
UFTouchStateUpdate, /**< A value or property of the touch changed */
529
UFTouchStateEnd, /**< The touch ended */
530
} UFTouchState;
531
532
/** Touch properties */
533
typedef enum UFTouchProperty {
534
/**
535
* Window server ID of the touch
536
*
537
* Value type: UFTouchId
538
*/
539
UFTouchPropertyId = 0,
540
/**
541
* State of the touch
542
*
543
* Value type: UFTouchState
544
*/
545
UFTouchPropertyState,
546
/**
547
* Location along X axis of touch relative to event window
548
*
549
* Value type: float
550
*
551
* The window server may provide touch location in window coordinate space.
552
* This property will be set where available.
553
*/
554
UFTouchPropertyWindowX,
555
/**
556
* Location along Y axis of touch relative to event window
557
*
558
* Value type: float
559
*
560
* The window server may provide touch location in window coordinate space.
561
* This property will be set where available.
562
*/
563
UFTouchPropertyWindowY,
564
/**
565
* Time of last touch state change
566
*
567
* Value type: 64-bit unsigned int
568
*
569
* See UFEventPropertyTime for the semantics of the value. If the touch has
570
* not changed during this frame, the value of this property will be less than
571
* the value of the UFEventPropertyTime event property for this frame.
572
*/
573
UFTouchPropertyTime,
574
/**
575
* Start time of touch
576
*
577
* Value type: 64-bit unsigned int
578
*
579
* See UFEventPropertyTime for the semantics of the value.
580
*/
581
UFTouchPropertyStartTime,
582
/**
583
* Whether the touch is owned by the client
584
*
585
* Value type: int with boolean semantics
586
*
587
* Some window servers have the concept of touch ownership. This property
588
* is only valid when the server supports touch ownership.
589
*/
590
UFTouchPropertyOwned,
591
/**
592
* Whether the touch has physically ended before the touch sequence has ended
593
*
594
* Value type: int with boolean semantics
595
*
596
* Some window servers have the concept of touch ownership. If a touch has
597
* ended before the client receives ownership, this property will be set to
598
* true. The property will also be set to true when the touch has ended before
599
* the client has accepted or rejected ownership of the touch sequence.
600
*/
601
UFTouchPropertyPendingEnd,
602
} UFTouchProperty;
603
604
/**
605
* Get the event file descriptor for the uTouch Frame context
606
*
607
* @param [in] handle The uTouch Frame context object
608
* @return A file descriptor for the context
609
*
610
* When events are available for processing, the file descriptor will be
611
* readable. Perform an 8-byte read from the file descriptor to clear the state.
612
* Refer to the EVENTFD(2) man page for more details.
613
*/
614
int frame_get_fd(UFHandle handle);
615
616
/**
617
* Get an event from the uTouch Frame context
618
*
619
* @param [in] handle The context object
620
* @param [out] event The retrieved event
621
* @return UFStatusSuccess or UFStatusErrorNoEvent
622
*
623
* The reference count of the returned event is implicity incremented once.
624
*/
625
UFStatus frame_get_event(UFHandle handle, UFEvent *event);
626
627
/**
628
* Get the value of a property of a device
629
*
630
* @param [in] device The device object (const)
631
* @param [in] property The property to retrieve a value for
632
* @param [out] value The value retrieved
633
* @return UFStatusSuccess or UFStatusErrorUnknownProperty
634
*/
635
UFStatus frame_device_get_property(UFDevice device, UFDeviceProperty property,
636
void *value);
637
638
/**
639
* Get a device touch axis by index
640
*
641
* @param [in] device The device object (const)
642
* @param [in] index The index of the axis to get
643
* @param [out] axis The axis retrieved
644
* @return UFStatusSuccess or UFStatusErrorInvalidAxis
645
*
646
* The index value must be greater than or equal to 0 and less than the number
647
* axes of the device.
648
*/
649
UFStatus frame_device_get_axis_by_index(UFDevice device, unsigned int index,
650
UFAxis *axis);
651
652
/**
653
* Get a device touch axis by axis type
654
*
655
* @param [in] device The device object (const)
656
* @param [in] type The axis type
657
* @param [out] axis The axis retrieved
658
* @return UFStatusSuccess or UFStatusErrorInvalidAxis
659
*
660
* UFStatusErrorInvalidAxis is returned if the device does not have an axis of
661
* the type requested.
662
*/
663
UFStatus frame_device_get_axis_by_type(UFDevice device, UFAxisType type,
664
UFAxis *axis);
665
666
/**
667
* Get the type of a touch device axis
668
*
669
* @param [in] axis The touch device axis (const)
670
* @return The type of the axis
671
*/
672
UFAxisType frame_axis_get_type(UFAxis axis);
673
674
/**
675
* Get the minimum value of a touch device axis
676
*
677
* @param [in] axis The touch device axis (const)
678
* @return The minimum value of the axis
679
*/
680
float frame_axis_get_minimum(UFAxis axis);
681
682
/**
683
* Get the maximum value of a touch device axis
684
*
685
* @param [in] axis The touch device axis (const)
686
* @return The maximum value of the axis
687
*/
688
float frame_axis_get_maximum(UFAxis axis);
689
690
/**
691
* Get the resolution of a touch device axis
692
*
693
* @param [in] axis The touch device axis (const)
694
* @return The resolution of the axis
695
*/
696
float frame_axis_get_resolution(UFAxis axis);
697
698
/**
699
* Increment the reference count of an event
700
*
701
* @param [in] event The event object
702
*/
703
void frame_event_ref(UFEvent event);
704
705
/**
706
* Decrement the reference count of an event
707
*
708
* @param [in] event The event object
709
*
710
* When the reference count reaches zero, the event is freed.
711
*/
712
void frame_event_unref(UFEvent event);
713
714
/**
715
* Get the value of a property of an event
716
*
717
* @param [in] event The event object (const)
718
* @param [in] property The property to retrieve a value for
719
* @param [out] value The value retrieved
720
* @return UFStatusSuccess or UFStatusErrorUnknownProperty
721
*/
722
UFStatus frame_event_get_property(UFEvent event, UFEventProperty property,
723
void *value);
724
725
/**
726
* Get the value of a property of a frame
727
*
728
* @param [in] frame The frame object (const)
729
* @param [in] property The property to retrieve a value for
730
* @param [out] value The value retrieved
731
* @return UFStatusSuccess or UFStatusErrorUnknownProperty
732
*/
733
UFStatus frame_frame_get_property(UFFrame frame, UFFrameProperty property,
734
void *value);
735
736
/**
737
* Get a touch of a frame by index
738
*
739
* @param [in] frame The frame object (const)
740
* @param [in] index The index of the touch to get
741
* @param [out] touch The touch retrieved
742
* @return UFStatusSuccess or UFStatusErrorInvalidTouch
743
*
744
* The index value must be greater than or equal to 0 and less than the number
745
* touches reported in the frame.
746
*/
747
UFStatus frame_frame_get_touch_by_index(UFFrame frame, unsigned int index,
748
UFTouch *touch);
749
750
/**
751
* Get a touch from a frame by the window server ID
752
*
753
* @param [in] frame The frame object (const)
754
* @param [in] touch_id The window server ID of the touch
755
* The value type of the touch ID is window server dependent. See
756
* UFTouchPropertyId for more details.
757
* @param [out] touch The touch object
758
* @return UFStatusSuccess or UFStatusErrorInvalidTouch
759
*/
760
UFStatus frame_frame_get_touch_by_id(UFFrame frame, UFTouchId touch_id,
761
UFTouch* touch);
762
763
/**
764
* Get the previous value of a property of a touch
765
*
766
* @param [in] frame The current frame object (const)
767
* @param [in] touch The current touch object (const)
768
* @param [in] property The property to retrieve a value for
769
* @param [out] value The value retrieved
770
* @return UFStatusSuccess, UFStatusErrorUnknownProperty, or
771
* UFStatusErrorInvalidTouch
772
*
773
* The previous value is the value of the property in the previous frame.
774
* UFStatusErrorInvalidTouch is returned if the touch did not exist in the
775
* previous frame.
776
*/
777
UFStatus frame_frame_get_previous_touch_property(UFFrame frame, UFTouch touch,
778
UFTouchProperty property,
779
void *value);
780
781
/**
782
* Get the previous value of an axis of a touch
783
*
784
* @param [in] frame The current frame object (const)
785
* @param [in] touch The current touch object (const)
786
* @param [in] type The axis to retrieve a value for
787
* @param [out] value The value retrieved
788
* @return UFStatusSuccess, UFStatusErrorInvalidAxis, or
789
* UFStatusErrorInvalidTouch
790
*
791
* The previous value is the value of the axis in the previous frame.
792
* UFStatusErrorInvalidTouch is returned if the touch did not exist in the
793
* previous frame.
794
*/
795
UFStatus frame_frame_get_previous_touch_value(UFFrame frame, UFTouch touch,
796
UFAxisType type, float* value);
797
798
/**
799
* Get the value of a property of a touch
800
*
801
* @param [in] touch The touch object (const)
802
* @param [in] property The property to retrieve a value for
803
* @param [out] value The value retrieved
804
* @return UFStatusSuccess or UFStatusErrorUnknownProperty
805
*/
806
UFStatus frame_touch_get_property(UFTouch touch, UFTouchProperty property,
807
void *value);
808
809
/**
810
* Get the value of an axis of a touch
811
*
812
* @param [in] touch The touch object (const)
813
* @param [in] type The axis to retrieve a value for
814
* @param [out] value The value retrieved
815
* @return UFStatusSuccess or UFStatusErrorInvalidAxis
816
*/
817
UFStatus frame_touch_get_value(UFTouch touch, UFAxisType type, float *value);
818
819
/**
820
* @defgroup v2-helpers Helper Functions
821
* These helper functions may be used in place of the generic property getters.
822
* They are limited to properties that are guaranteed to exist in all instances
823
* of the objects.
824
* @{
825
*/
826
827
/**
828
* Get the type of an event
829
*
830
* @param [in] event The event object (const)
831
* @return The type of the event
832
*/
833
UFEventType frame_event_get_type(UFEvent event);
834
835
/**
836
* Get the time of an event
837
*
838
* @param [in] event The event object (const)
839
* @return The time of the event
840
*/
841
uint64_t frame_event_get_time(UFEvent event);
842
843
/**
844
* Get the number of axes of a device
845
*
846
* @param [in] device The device object (const)
847
* @return The number of axes
848
*/
849
unsigned int frame_device_get_num_axes(UFDevice device);
850
851
/**
852
* Get the number of touches in the frame
853
*
854
* @param [in] frame The frame object (const)
855
* @return The number of touches
856
*/
857
uint32_t frame_frame_get_num_touches(UFFrame frame);
858
859
/**
860
* Get the device of a frame
861
*
862
* @param [in] frame The frame context object (const)
863
* return The device of the window context
864
*/
865
UFDevice frame_frame_get_device(UFFrame frame);
866
867
/**
868
* Get the window ID of a frame
869
*
870
* @param [in] frame The frame context object (const)
871
* @return The window server ID of the window of the frame
872
*/
873
UFWindowId frame_frame_get_window_id(UFFrame frame);
874
875
/**
876
* Get the window server ID of a touch
877
*
878
* @param [in] touch The touch context object (const)
879
* @return The window server ID of the touch
880
*/
881
UFTouchId frame_touch_get_id(UFTouch touch);
882
883
/**
884
* Get the state of a touch
885
*
886
* @param [in] touch The touch object (const)
887
* @return The state of the touch
888
*/
889
UFTouchState frame_touch_get_state(UFTouch touch);
890
891
/**
892
* Get the X window coordinate of a touch
893
*
894
* @param [in] touch The touch object (const)
895
* @return The X window coordinate of the touch
896
*/
897
float frame_touch_get_window_x(UFTouch touch);
898
899
/**
900
* Get the Y window coordinate of a touch
901
*
902
* @param [in] touch The touch object (const)
903
* @return The Y window coordinate of the touch
904
*/
905
float frame_touch_get_window_y(UFTouch touch);
906
907
/**
908
* Get the X device coordinate of a touch
909
*
910
* @param [in] touch The touch object (const)
911
* @return The X device coordinate of the touch
912
*/
913
float frame_touch_get_device_x(UFTouch touch);
914
915
/**
916
* Get the Y device coordinate of a touch
917
*
918
* @param [in] touch The touch object (const)
919
* @return The Y device coordinate of the touch
920
*/
921
float frame_touch_get_device_y(UFTouch touch);
922
923
/**
924
* Get the time of a touch state change
925
*
926
* @param [in] touch The touch object (const)
927
* @return The time of the touch state change
928
*/
929
uint64_t frame_touch_get_time(UFTouch touch);
930
931
/**
932
* Get the start time of a touch
933
*
934
* @param [in] touch The touch object (const)
935
* @return The start time of the touch
936
*/
937
uint64_t frame_touch_get_start_time(UFTouch touch);
938
939
/** @} */
940
941
/** @} */
942
303
943
#ifdef __cplusplus
304
944
}
305
945
#endif
306
946
307
#endif
947
#endif // UTOUCH_FRAME_UTOUCH_FRAME_H_
Loggerhead is a web-based interface for Breezy
Version: 2.0.1