Vibe scores

Vibration patterns stored as resources, and their selection per alert type. More...

Modules
	Vibe clients
	Vibe score selected by the user for each kind of alert.
	Vibe intensity
	Default strength of all vibrations.
	Vibe score catalog
	Built-in vibe scores, their names and the alerts they can be used for.

Data Structures
struct	VibeScore
	Vibe score, as stored in the resource after the signature. More...
struct	VibeNote
	Vibration step of a vibe score. More...

Macros
#define	VIBE_SCORE_VERSION   (1)
	Highest vibe score format version supported.
#define	VIBE_SIGNATURE   PBL_FOURCC('V', 'I', 'B', 'E')
	Signature at the start of a vibe score resource.
#define	VIBE_DATA_OFFSET   sizeof(VIBE_SIGNATURE)
	Offset of the VibeScore within the resource.

Typedefs
typedef uint8_t	VibeNoteIndex
	Index into the notes table of a vibe score.

Enumerations
enum	VibeAttributeId { VibeAttributeId_Invalid = 0x00 , VibeAttributeId_Notes = 0x01 , VibeAttributeId_Pattern = 0x02 , VibeAttributeId_RepeatDelay = 0x03 }
	Attributes of a vibe score. More...

Functions
VibeScore *	vibe_score_create_with_resource_system (ResAppNum app_num, uint32_t resource_id)
	Load a vibe score from the resources of an app.
VibeScore *	vibe_score_create_with_resource (uint32_t resource_id)
	Load a vibe score from the resources of the calling process.
bool	vibe_score_validate (VibeScore *score, uint32_t data_size)
	Check whether a vibe score is well formed.
unsigned int	vibe_score_get_duration_ms (VibeScore *score)
	Get the duration of one playback of a vibe score.
unsigned int	vibe_score_get_repeat_delay_ms (VibeScore *score)
	Get the delay before a vibe score repeats.
void	vibe_score_do_vibe (VibeScore *score)
	Play a vibe score once.
void	vibe_score_destroy (VibeScore *score)
	Free a vibe score.

Detailed Description

Vibration patterns stored as resources, and their selection per alert type.

A vibe score resource starts with VIBE_SIGNATURE, followed by a VibeScore whose attribute list holds a table of VibeNote (VibeAttributeId_Notes), the pattern as indices into that table (VibeAttributeId_Pattern) and optionally a delay before the pattern repeats (VibeAttributeId_RepeatDelay).

VibeScore *score = vibe_client_get_score(VibeClient_Notifications);
if (score) {
  vibe_score_do_vibe(score);
  vibe_score_destroy(score);
}

---

Data Structure Documentation

VibeScore

struct VibeScore

Vibe score, as stored in the resource after the signature.

Data Fields
struct pbl_generic_attr_list	attr_list	Attributes, see VibeAttributeId.
uint16_t	attr_list_size	Size of attr_list in bytes.
uint8_t	reserved[4]	Reserved.
uint16_t	version	Format version, at most VIBE_SCORE_VERSION.

VibeNote

struct VibeNote

Vibration step of a vibe score.

Data Fields
uint8_t	brake_duration_ms	Time the motor brakes afterwards, in milliseconds.
int8_t	strength	Motor strength, -100 to 100.
uint16_t	vibe_duration_ms	Time the motor runs, in milliseconds.

Macro Definition Documentation

VIBE_DATA_OFFSET

#define VIBE_DATA_OFFSET   sizeof(VIBE_SIGNATURE)

Offset of the VibeScore within the resource.

VIBE_SCORE_VERSION

#define VIBE_SCORE_VERSION   (1)

Highest vibe score format version supported.

VIBE_SIGNATURE

#define VIBE_SIGNATURE   PBL_FOURCC('V', 'I', 'B', 'E')

Signature at the start of a vibe score resource.

Typedef Documentation

VibeNoteIndex

typedef uint8_t VibeNoteIndex

Index into the notes table of a vibe score.

Enumeration Type Documentation

VibeAttributeId

enum VibeAttributeId

Attributes of a vibe score.

Enumerator
VibeAttributeId_Invalid	Invalid attribute.
VibeAttributeId_Notes	Table of VibeNote.
VibeAttributeId_Pattern	Pattern, as a sequence of VibeNoteIndex into the notes table.
VibeAttributeId_RepeatDelay	Delay before the pattern repeats, uint16_t in milliseconds (at most 60000).

Function Documentation

vibe_score_create_with_resource()

VibeScore * vibe_score_create_with_resource

(

uint32_t

resource_id

)

Load a vibe score from the resources of the calling process.

Parameters

resource_id

Resource ID of the score.

Returns

Validated score, to be freed with vibe_score_destroy(), or NULL.

vibe_score_create_with_resource_system()

VibeScore * vibe_score_create_with_resource_system	(	ResAppNum	app_num,
		uint32_t	resource_id
	)

Load a vibe score from the resources of an app.

Parameters

app_num	Resource bank to load from.
resource_id	Resource ID of the score.

Returns

Validated score allocated on the caller's heap, to be freed with vibe_score_destroy(), or NULL if missing, invalid or out of memory.

vibe_score_destroy()

void vibe_score_destroy

(

VibeScore *

score

)

Free a vibe score.

Parameters

score

Score from vibe_score_create_with_resource() or vibe_score_create_with_resource_system(), may be NULL.

vibe_score_do_vibe()

void vibe_score_do_vibe

(

VibeScore *

score

)

Play a vibe score once.

Queues the pattern and starts the vibe motor. Does nothing if a vibe pattern is already playing.

Parameters

score

Valid score.

vibe_score_get_duration_ms()

unsigned int vibe_score_get_duration_ms

(

VibeScore *

score

)

Get the duration of one playback of a vibe score.

Parameters

score

Valid score, may be NULL.

Returns

Total vibe and brake time of the pattern in milliseconds, 0 for NULL.

vibe_score_get_repeat_delay_ms()

unsigned int vibe_score_get_repeat_delay_ms

(

VibeScore *

score

)

Get the delay before a vibe score repeats.

Parameters

score

Score, may be NULL.

Returns

Repeat delay in milliseconds, or 0 if the score has none.

vibe_score_validate()

bool vibe_score_validate	(	VibeScore *	score,
		uint32_t	data_size
	)

Check whether a vibe score is well formed.

Checks the version, the sizes of all attributes, that notes and pattern exist, that the pattern only references existing notes and that the repeat delay is in range.

Parameters

score	Score to check, may be NULL.
data_size	Size of score in bytes.

Returns

true if the score is valid.