CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Friends | List of all members
cugl::Accelerometer Class Reference

#include <CUAccelerometer.h>

Inheritance diagram for cugl::Accelerometer:
cugl::InputDevice

Public Types

typedef std::function< void(const AccelerationEvent &event, bool focus)> Listener
 

Public Member Functions

float getThreshold () const
 
void setThreshold (float value) const
 
float getAccelerationX () const
 
float getAccelerationY () const
 
float getAccelerationZ () const
 
const Vec3 getAcceleration () const
 
float getDeltaX () const
 
float getDeltaY () const
 
float getDeltaZ () const
 
const Vec3 getDelta () const
 
virtual bool requestFocus (Uint32 key) override
 
bool isListener (Uint32 key) const
 
const Listener getListener (Uint32 key) const
 
bool addListener (Uint32 key, Listener listener)
 
bool removeListener (Uint32 key)
 
virtual void clearState () override
 
virtual bool updateState (const SDL_Event &event, const Timestamp &stamp) override
 
virtual void queryEvents (std::vector< Uint32 > &eventset) override
 
- Public Member Functions inherited from cugl::InputDevice
Uint32 acquireKey ()
 
Uint32 currentFocus () const
 
void releaseFocus ()
 

Friends

class Input
 

Additional Inherited Members

- Static Public Attributes inherited from cugl::InputDevice
static const Uint32 RESERVED_KEY = UINT32_MAX
 
- Protected Member Functions inherited from cugl::InputDevice
 InputDevice ()
 
virtual ~InputDevice ()
 
bool initWithName (const std::string name)
 
- Protected Attributes inherited from cugl::InputDevice
std::string _name
 
Uint32 _focus
 
Uint32 _nextKey
 

Detailed Description

This class is an input device representing the accelerometer

This input device a three-axis accelerometer. It measures the affects of gravity on each of the three axis, allowing you to measure the rotational orientation of the device.

As with most devices, we provide support for both listeners and polling the mouse. Polling the accelerometer will query the rotational axes at the start of the frame. The advantage of listeners is that they are a lot less frequent. If the acceleration does not change significantly from frame to frame, no event will be generated. See the method Accelerometer#getThreshold() for more information.

Listeners are guaranteed to catch acceleration changes, as long as they are detected by the OS. However, listeners are not called as soon as the event happens. Instead, the events are queued and processed at the start of the animation frame, before the method Application#update(float) is called.

Member Typedef Documentation

◆ Listener

This type represents a listener for the Accelerometer class.

In CUGL, listeners are implemented as a set of callback functions, not as objects. This allows each listener to implement as much or as little functionality as it wants. A listener is identified by a key which should be a globally unique unsigned int.

An event is delivered whenever the accleration delta (the difference between the current and previous value) exceeds the device threshold. See the method Accelerometer#getThreshold() for more information.

Listeners are guaranteed to be called at the start of an animation frame, before the method Application#update(float).

While accleration listeners do not traditionally require focus like a keyboard does, we have included that functionality. While only one listener can have focus at a time, all listeners will receive input from the Acclerometer device.

The function type is equivalent to

 std::function<void(const std::string& value, Timestamp stamp, bool focus)>
Parameters
eventThe acceleration event
focusWhether the listener currently has focus

Member Function Documentation

◆ addListener()

bool cugl::Accelerometer::addListener ( Uint32  key,
Listener  listener 
)

Adds an acceleration listener for the given object key

There can only be one listener for a given key. If there is already a listener for the key, the method will fail and return false. You must remove a listener before adding a new one for the same key.

Parameters
keyThe identifier for the listener
listenerThe listener to add
Returns
true if the listener was succesfully added

◆ clearState()

virtual void cugl::Accelerometer::clearState ( )
overridevirtual

Clears the state of this input device, readying it for the next frame.

Many devices keep track of what happened "this" frame. This method is necessary to advance the frame.

Implements cugl::InputDevice.

◆ getAcceleration()

const Vec3 cugl::Accelerometer::getAcceleration ( ) const
inline

Returns all three axes of acceleration.

This value will be updated every animation frame, regardless of the value of threshold.

Returns
all three axes of acceleration.

◆ getAccelerationX()

float cugl::Accelerometer::getAccelerationX ( ) const
inline

Returns the x-axis acceleration.

This value will be updated every animation frame, regardless of the value of threshold.

Returns
the x-axis acceleration.

◆ getAccelerationY()

float cugl::Accelerometer::getAccelerationY ( ) const
inline

Returns the y-axis acceleration.

This value will be updated every animation frame, regardless of the value of threshold.

Returns
the y-axis acceleration.

◆ getAccelerationZ()

float cugl::Accelerometer::getAccelerationZ ( ) const
inline

Returns the z-axis acceleration.

This value will be updated every animation frame, regardless of the value of threshold.

Returns
the z-axis acceleration.

◆ getDelta()

const Vec3 cugl::Accelerometer::getDelta ( ) const
inline

Returns all three axes of the change in rotation.

This change is measured against the previous animation frame, not the previously recorded value. The polling methods are always updated and ignore the threshold.

Returns
all three axes of the change in rotation.

◆ getDeltaX()

float cugl::Accelerometer::getDeltaX ( ) const
inline

Returns the x-axis change in rotation.

This change is measured against the previous animation frame, not the previously recorded value. The polling methods are always updated and ignore the threshold.

Returns
the x-axis change in rotation.

◆ getDeltaY()

float cugl::Accelerometer::getDeltaY ( ) const
inline

Returns the y-axis change in rotation.

This change is measured against the previous animation frame, not the previously recorded value. The polling methods are always updated and ignore the threshold.

Returns
the y-axis change in rotation.

◆ getDeltaZ()

float cugl::Accelerometer::getDeltaZ ( ) const
inline

Returns the z-axis change in rotation.

This change is measured against the previous animation frame, not the previously recorded value. The polling methods are always updated and ignore the threshold.

Returns
the z-axis change in rotation.

◆ getListener()

const Listener cugl::Accelerometer::getListener ( Uint32  key) const

Returns the acceleration listener for the given object key

If there is no listener for the given key, it returns nullptr.

Parameters
keyThe identifier for the listener
Returns
the accleration listener for the given object key

◆ getThreshold()

float cugl::Accelerometer::getThreshold ( ) const
inline

Returns the event reporting threshold of this accelerometer.

We only report accerelation events when the device orientation changes significantly. By significantly, we mean that the difference between the current acceleration and the last generated event (measured as the square of the Euclidean distance) is above this threshold.

By default, this value is 0.1f, which is good enough for most applications. If you want reporting every animation frame, set this value to 0.

Returns
the event reporting threshold of this accelerometer.

◆ isListener()

bool cugl::Accelerometer::isListener ( Uint32  key) const

Returns true if key represents a listener object

Parameters
keyThe identifier for the listener
Returns
true if key represents a listener object

◆ queryEvents()

virtual void cugl::Accelerometer::queryEvents ( std::vector< Uint32 > &  eventset)
overridevirtual

Determine the SDL events of relevance and store there types in eventset.

An SDL_EventType is really Uint32. This method stores the SDL event types for this input device into the vector eventset, appending them to the end. The Input dispatcher then uses this information to set up subscriptions.

Parameters
eventsetThe set to store the event types.

Implements cugl::InputDevice.

◆ removeListener()

bool cugl::Accelerometer::removeListener ( Uint32  key)

Removes the acceleration listener for the given object key

If there is no active listener for the given key, this method fails and returns false.

Parameters
keyThe identifier for the listener
Returns
true if the listener was succesfully removed

◆ requestFocus()

virtual bool cugl::Accelerometer::requestFocus ( Uint32  key)
overridevirtual

Requests focus for the given identifier

Only a listener can have focus. This method returns false if key does not refer to an active listener

Parameters
keyThe identifier for the focus object
Returns
false if key does not refer to an active listener

Reimplemented from cugl::InputDevice.

◆ setThreshold()

void cugl::Accelerometer::setThreshold ( float  value) const

Sets the event reporting threshold of this accelerometer.

We only report accerelation events when the device orientation changes significantly. By significantly, we mean that the difference between the current acceleration and the last generated event (measured as the square of the Euclidean distance) is above this threshold.

By default, this value is 0.1f, which is good enough for most applications. If you want reporting every animation frame, set this value to 0.

Parameters
valueThe event reporting threshold of this accelerometer.

◆ updateState()

virtual bool cugl::Accelerometer::updateState ( const SDL_Event &  event,
const Timestamp stamp 
)
overridevirtual

Processes an SDL_Event

The dispatcher guarantees that an input device only receives events that it subscribes to.

Parameters
eventThe input event to process
stampThe event timestamp in CUGL time
Returns
false if the input indicates that the application should quit.

Implements cugl::InputDevice.


The documentation for this class was generated from the following file: