---

2.5.3 Incrementing Spur ¶

An actor emits output signals adaptively according to input signals, spur increments, and time increments supplied to it. Spur increments are probabilistic indicators of efficiency of output signal selection. An arbitrary number of emitted output signals might cause an arbitrary number of spur increments followed in arbitrary delays when an actor was emitting other output signals.

An actor supports multiple spur types. See Spur-Driven Behavior, for the definition of spur type. The field nspur of qsmm_actor_desc_s structure passed to the function qsmm_actor_create sets the number of spur types of an actor. The function qsmm_get_actor_nspur returns that number for a created actor. A spur increment is an increment of spur with a particular type.

To a spur type there correspond the following parameters: a type of time for computing spur increment velocity, spur weight, and a way of spur perception. A list of spur types with the aforementioned parameters and rules for performing spur increments specify the spur scheme of an actor.

Use the following function to increment the value of spur with a specific type.

Function: int qsmm_actor_spur_delta (qsmm_actor_t actor, int spur_type, double spur_delta) ¶

This function increments by spur_delta the value of spur with type spur_type an actor is accumulating. Spur types have zero-based indices. The value of spur_delta can be negative.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

One of the following conditions is true:

• spur_type is negative;
• spur_type is too large;
• spur_delta is non-finite.

QSMM_ERR_INFIN

An incremented spur value would be infinite.

Use the following function to get the current value of spur with a specific type.

Function: int qsmm_get_actor_spur (qsmm_actor_t actor, int spur_type, double *spur_p) ¶

This function sets *spur_p equal to the current value of spur with type spur_type an actor is accumulating. Spur types have zero-based indices. If spur_p is NULL, the function does not set *spur_p. Otherwise, *spur_p is finite.

On success, the function returns a non-negative value. If spur_type is negative or too large, the function returns negative error code QSMM_ERR_INVAL.