Interface for running and controlling action flow. More...

#include <ActionPlayer.hpp>

Public Types
enum	State { RUNNING = 0 , PAUSED , STOPPED }
	The status of the player. More...
typedef ActionPlayer	self_type
typedef std::vector< const char * >	action_names

Public Member Functions
	ActionPlayer (const ActionPlayer &rhs)=delete
	Disabled copy constructor.
ActionPlayer &	operator= (const ActionPlayer &rhs)=delete
	Disabled copy assignment operator.
bool	idle () const
	Get the status of the action queue.
nom::size_type	num_actions () const
	Get the number of actions enqueued.
ActionPlayer::State	player_state () const
	Get the control status of the queue.
void	pause ()
	Freeze the enqueued actions from advancing forward in time.
void	resume ()
	Resume the advancement of time for the enqueued actions.
void	stop ()
	Reset the enqueued actions back to its initial starting state.
bool	action_running (const std::string &action_id) const
	Get the completion status of an action.
bool	cancel_action (const std::string &action_id)
	Stop executing an action.
void	cancel_actions (const action_names &actions)
void	cancel_actions ()
	Stop executing the enqueued actions.
bool	run_action (const std::shared_ptr< IActionObject > &action)
	Enqueue an action.
bool	run_action (const std::shared_ptr< IActionObject > &action, const action_callback_func &completion_func)
	Enqueue an action with a completion callback.
bool	update (real32 delta_time)
	Run the enqueued actions' update loop.

Private Types
typedef std::map< std::string, std::unique_ptr< DispatchQueue > >	container_type
typedef container_type::iterator	container_iterator

Private Member Functions
bool	run_action (const std::shared_ptr< IActionObject > &action, std::unique_ptr< DispatchQueue > dispatch_queue, const action_callback_func &completion_func)
	Enqueue an action that runs on a specific dispatch queue.

Private Attributes
ActionPlayer::State	player_state_
container_type	actions_
	Enqueued actions.
std::deque< container_iterator >	free_list_
	The actions pending removal.

Static Private Attributes
static const char *	DEBUG_CLASS_NAME

Detailed Description

Interface for running and controlling action flow.

This is the high-level interface for scheduling and controlling the flow of actions. You may find that using multiple instances of the interface is ideal if you have several action groups that can be managed independently from each other.

TODO: This documentation section is a STUB!

Usage Examples

// Declared somewhere accessible by the game
nom::ActionPlayer actions;
 
// Your main game loop
while(game_running == true)
{
  // calculate delta_time for this frame
 
  // ...Process game, input, etc. events
 
  // ...Process game updates...
 
  actions.update(delta_time);
 
  // ...Process rendering...
}

TEST_F(ActionTest, MoveByAction)
{
  // Testing parameters
  const float DURATION = 2.5f;
  const float SPEED_MOD = NOM_ACTION_TEST_FLAG(speed);
  const IActionObject::timing_curve_func TIMING_MODE =
    NOM_ACTION_TEST_FLAG(timing_curve);
  const Point2i TRANSLATE_POS( Point2i(200,0) );
  const uint32 FPS = NOM_ACTION_TEST_FLAG(fps);
 
  // Initial texture position and size
  const Point2i RECT_POS(Point2i::zero);
  const Size2i RECT_SIZE(WINDOW_DIMS.w/4, WINDOW_DIMS.h);
  const Point2i EXPECTED_TEX_POS(TRANSLATE_POS);
 
  auto rect = std::make_shared<Rectangle>(
    Rectangle( IntRect(RECT_POS, RECT_SIZE), Color4i::Green) );
  ASSERT_TRUE(rect != nullptr);
 
  auto sprite = nom::make_shared_sprite( rect->texture() );
  ASSERT_TRUE(sprite != nullptr);
 
  auto translate =
    nom::create_action<MoveByAction>(sprite, TRANSLATE_POS, DURATION);
  ASSERT_TRUE(translate != nullptr);
 
  auto action0 =
    nom::create_action<GroupAction>( {translate} );
  ASSERT_TRUE(action0 != nullptr);
  action0->set_timing_curve(TIMING_MODE);
  action0->set_speed(SPEED_MOD);
  action0->set_name("action0");
 
  EXPECT_EQ(0, this->player.num_actions() );
  this->run_action_ret =
  this->player.run_action(action0, [=]() {
 
    EXPECT_EQ( EXPECTED_TEX_POS, sprite->position() );
    EXPECT_EQ(1, this->player.num_actions() );
 
    this->expected_action_params(action0.get(), 1);
    this->expected_common_params(translate.get(), DURATION, SPEED_MOD);
  });
  EXPECT_EQ(true, this->run_action_ret)
  << "Failed to queue the action!";
  EXPECT_EQ(1, this->player.num_actions() );
 
  this->append_update_callback( [=](float) {
    if( this->expected_min_duration(DURATION, SPEED_MOD) == true ) {
      this->quit();
    }
  });
 
  this->append_render_queue( sprite.get() );
  this->append_frame_interval(FPS);
 
  EXPECT_EQ( NOM_EXIT_SUCCESS, this->on_run() );
}

References (Conceptual)

SKNode

Definition at line 49 of file ActionPlayer.hpp.

Member Typedef Documentation

◆ action_names

typedef std::vector<const char*> nom::ActionPlayer::action_names

See also: ::actions_running, ::cancel_actions

Definition at line 55 of file ActionPlayer.hpp.

◆ container_iterator

typedef container_type::iterator nom::ActionPlayer::container_iterator

private

Definition at line 206 of file ActionPlayer.hpp.

◆ container_type

typedef std::map<std::string, std::unique_ptr<DispatchQueue> > nom::ActionPlayer::container_type

private

Definition at line 204 of file ActionPlayer.hpp.

◆ self_type

typedef ActionPlayer nom::ActionPlayer::self_type

Definition at line 52 of file ActionPlayer.hpp.

Member Enumeration Documentation

◆ State

enum nom::ActionPlayer::State

The status of the player.

Definition at line 58 of file ActionPlayer.hpp.

Member Function Documentation

◆ action_running()

bool nom::ActionPlayer::action_running ( const std::string & action_id ) const

Get the completion status of an action.

Parameters

action_id The unique identifier of the action.

Returns: Boolean TRUE if the action has completed, and boolean FALSE if the action has not completed.

See also: nom::IActionObject::set_name.

◆ cancel_action()

bool nom::ActionPlayer::cancel_action ( const std::string & action_id )

Stop executing an action.

Parameters

action_id The unique identifier of the action to stop.

See also: nom::IActionObject::set_name.

◆ cancel_actions()

void nom::ActionPlayer::cancel_actions ( )

Stop executing the enqueued actions.

Remarks: This will instantaneously stop running all enqueued actions.

◆ idle()

bool nom::ActionPlayer::idle ( ) const

Get the status of the action queue.

Returns: Boolean FALSE when one or more actions are running, and boolean TRUE when all actions have been completed and have been removed from the queue.

◆ pause()

void nom::ActionPlayer::pause ( )

Freeze the enqueued actions from advancing forward in time.

Remarks: Resuming from this control state will continue iterating the enqueued actions forward in time from where it last left off.

Note: The player state is set to nom::ActionPlayer::State::PAUSED.

◆ player_state()

ActionPlayer::State nom::ActionPlayer::player_state ( ) const

Get the control status of the queue.

Returns: One of the nom::ActionPlayer::State enumeration values.

◆ resume()

void nom::ActionPlayer::resume ( )

Resume the advancement of time for the enqueued actions.

Note: The player state is set to ActionPlayer::State::RUNNING.

See also: nom::ActionPlayer::pause, nom::ActionPlayer::stop

◆ run_action() [1/3]

bool nom::ActionPlayer::run_action ( const std::shared_ptr< IActionObject > & action )

Enqueue an action.

Parameters

action The action to run; NULL actions are valid.

Remarks: If an action using the same key is already running, it is removed before the new action is added.

See also: nom::ActionPlayer::update

◆ run_action() [2/3]

bool nom::ActionPlayer::run_action	(	const std::shared_ptr< IActionObject > &	action,
		const action_callback_func &	completion_func )

Enqueue an action with a completion callback.

Parameters

action	The action to run; NULL actions are valid.
completion_func	The function to call when the action is completed – passing NULL here is valid.

Remarks: If an action using the same key is already running, it is removed before the new action is added.

See also: nom::ActionPlayer::update

◆ run_action() [3/3]

bool nom::ActionPlayer::run_action	(	const std::shared_ptr< IActionObject > &	action,
		std::unique_ptr< DispatchQueue >	dispatch_queue,
		const action_callback_func &	completion_func )

private

Enqueue an action that runs on a specific dispatch queue.

Parameters

action	The action to run; NULL actions are valid.
completion_func	The function to call when the action is completed – passing NULL here is valid.
dispatch_queue	A valid nom::DispatchQueue to run the action on.

Remarks: It is not safe to enqueue more than one action per nom::DispatchQueue instance. When two or more actions share the same instance, it runs the risk of causing memory access violations in the form of double-freeing their dispatch queues upon completion (I believe this actually happens in ActionPlayer::update, but alas!). Using a reference counting mechanism, such as shared_ptr, resolves the issue, but if only that was the end of it ... The update loop in nom::DispatchQueue iterates through actions sequentially, which breaks actions that are intended to run in parallel, i.e.: nom::GroupAction – but even that problem is trivial to solve. The ~25..50% performance penalty observed made me decide that it was not worth the trouble, at least until I can find a use case for this issue.

◆ stop()

void nom::ActionPlayer::stop ( )

Reset the enqueued actions back to its initial starting state.

Remarks: This resets the state of the enqueued actions back to its initial state, i.e.: before being executed. Resuming from this control state will restart the enqueued actions from their initial state.

Note: The player state is set to nom::ActionPlayer::State::STOPPED.

◆ update()

bool nom::ActionPlayer::update ( real32 delta_time )

Run the enqueued actions' update loop.

Parameters

delta_time Reserved for application-defined implementations.

Returns: Boolean TRUE when one or more actions are running, and boolean FALSE when all actions have been completed.

Remarks: This method must be called from your application's loop.

See also: nom::ActionPlayer::idle

Member Data Documentation

◆ actions_

container_type nom::ActionPlayer::actions_

private

Enqueued actions.

Definition at line 211 of file ActionPlayer.hpp.

◆ DEBUG_CLASS_NAME

const char* nom::ActionPlayer::DEBUG_CLASS_NAME

staticprivate

Definition at line 201 of file ActionPlayer.hpp.

◆ free_list_

std::deque<container_iterator> nom::ActionPlayer::free_list_

private

The actions pending removal.

Definition at line 214 of file ActionPlayer.hpp.

◆ player_state_

ActionPlayer::State nom::ActionPlayer::player_state_

private

Definition at line 208 of file ActionPlayer.hpp.

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

/home/jeff/Projects/nomlib.git/include/nomlib/actions/ActionPlayer.hpp

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Usage Examples

References (Conceptual)

Member Typedef Documentation

◆ action_names

◆ container_iterator

◆ container_type

◆ self_type

Member Enumeration Documentation

◆ State

Member Function Documentation

◆ action_running()

◆ cancel_action()

◆ cancel_actions()

◆ idle()

◆ pause()

◆ player_state()

◆ resume()

◆ run_action() [1/3]

◆ run_action() [2/3]

◆ run_action() [3/3]

◆ stop()

◆ update()

Member Data Documentation

◆ actions_

◆ DEBUG_CLASS_NAME

◆ free_list_

◆ player_state_