Callbacks
[Framework]

Collaboration diagram for Callbacks:

Typedefs
typedef boost::optional< LRESULT >	tk11::Message_Result
	Optional result of window procedure.
typedef boost::function< void(ID3D11Device_ptr)>	tk11::Init_Callback
	Callback type for scene initialization.
typedef boost::function< void(ID3D11DeviceContext_ptr, ID3D11RenderTargetView_ptr, ID3D11DepthStencilView_ptr)>	tk11::Render_Callback
	Callback type for scene rendering.
typedef boost::function< void(ID3D11DeviceContext_ptr)>	tk11::Aux_Render_Callback
	Callback type for auxiliary scene rendering.
typedef boost::function< void(const Duration &)>	tk11::Update_Callback
	Callback type for scene update.
typedef boost::function< void(unsigned int, unsigned int, bool, ID3D11Device_ptr, IDXGISwapChain_ptr, ID3D11Texture2D_ptr)>	tk11::Resize_Callback
	Callback type for target window resize.
typedef boost::function < Message_Result(HWND, UINT, WPARAM, LPARAM)>	tk11::Message_Callback
	Callback type for windows message hook.
typedef boost::function< void()>	tk11::Deactivate_Callback
	Callback type for window deactivation.
typedef boost::function< void()>	tk11::Activate_Callback
	Callback type for window activation.
typedef boost::function< void(int, int)>	tk11::Mouse_Move_Callback
	Callback type for mouse pointer movement.
typedef boost::function< void()>	tk11::Mouse_Enter_Callback
	Callback type for mouse pointer entering the window.
typedef boost::function< void()>	tk11::Mouse_Leave_Callback
	Callback type for mouse pointer leaving the window.
typedef boost::function< void(Mouse_Button, int, int)>	tk11::Mouse_Down_Callback
	Callback type for mouse button press.
typedef boost::function< void(Mouse_Button, int, int)>	tk11::Mouse_Up_Callback
	Callback type for mouse button release.
typedef boost::function< void(int, int)>	tk11::Mouse_Motion_Callback
	Callback type for high precision mouse motion.
typedef boost::function< void(int, int, int)>	tk11::Mouse_Wheel_Callback
	Callback type for mouse wheel motion.
typedef boost::function< void(unsigned int)>	tk11::Key_Down_Callback
	Callback type for key press.
typedef boost::function< void(unsigned int)>	tk11::Key_Up_Callback
	Callback type for key release.
typedef boost::function< void(unsigned int)>	tk11::Key_Repeat_Callback
	Callback type for key repeat.
typedef boost::function< void(unsigned int)>	tk11::Char_Input_Callback
	Callback type for character input.
Enumerations
enum	tk11::Mouse_Button { tk11::left_button = 0, tk11::middle_button = 1, tk11::right_button = 2, tk11::extra_button1 = 3, tk11::extra_button2 = 4 }
	Mouse button identifiers. More...
Functions
void	init (tk11::ID3D11Device_ptr device)
	Callback for scene initialization (callback).
void	render (tk11::ID3D11DeviceContext_ptr context, tk11::ID3D11RenderTargetView_ptr render_target, ID3D11DepthStencilView_ptr depth_stencil)
	Callback for scene rendering (callback).
void	aux_render (tk11::ID3D11DeviceContext_ptr context)
	Callback for auxiliary rendering (callback).
void	update (const tk11::Duration &elapsed_time)
	Callback for auxiliary rendering (callback).
void	resize (unsigned int x_resolution, unsigned int y_resolution, bool fullscreen, tk11::ID3D11Device_ptr device, tk11::IDXGISwapChain_ptr swap_chain, tk11::ID3D11Texture2D_ptr back_buffer)
	Callback for target window resize (callback).
tk11::Message_Result	message (HWND window, UINT message, WPARAM wparam, LPARAM lparam)
	Callback for windows message hook (callback).
void	deactivate ()
	Callback for window deactivation (callback).
void	activate ()
	Callback for window activation (callback).
void	mouse_move (int x, int y)
	Callback for mouse pointer movement (callback).
void	mouse_enter ()
	Callback for mouse pointer entering the window (callback).
void	mouse_leave ()
	Callback for mouse pointer leaving the window (callback).
void	mouse_down (tk11::Mouse_Button button, int x, int y)
	Callback for mouse button press (callback).
void	mouse_up (tk11::Mouse_Button button, int x, int y)
	Callback for mouse button release (callback).
void	mouse_motion (int delta_x, int delta_y)
	Callback for high-precision mouse motion (callback).
void	mouse_wheel (int delta, int x, int y)
	Callback for mouse wheel movement (callback).
void	key_down (unsigned int key)
	Callback for key press (callback).
void	key_up (unsigned int key)
	Callback for key release (callback).
void	key_repeat (unsigned int key)
	Callback for key repeat (callback).
void	char_input (unsigned int char_)
	Callback for character input(callback).
Variables
const boost::none_t	tk11::not_handled = boost::none
	Default result of a window procedure.

Detailed Description

Callbacks are used by the framework to call functions or class methods of the application at certain events. This is similar to callbacks in GLUT or other graphics toolkits.

Callbacks are represented as boost::function objects. This gives application programmers maximum flexibility. On the one hand, it is possible to simply assign a function pointer (to a free function) to a callback, which is as simple as assigning callbacks in GLUT. On the other hand, the application developer can use boost::bind to assign member functions of objects as callbacks (delegates).

For more information, see http://www.boost.org/doc/libs/1_42_0/doc/html/function.html and http://www.boost.org/doc/libs/1_42_0/libs/bind/bind.html

Callbacks for a specific window are set in the tk11::Window_Parameters structure when creating a window. Global callbacks are set in the tk11::Framework_Parameters structure when creating the framework.

Exceptions

Callbacks, in general, are allowed to throw exceptions. The framework is exception-neutral and exception-safe, which means that resources will be released if necessary, and the method of the framework which invoked the callback (either the constructor or the run/frame method) will rethrow the exception.

In particular, if an exception is thrown while the main loop was running, the application may choose to handle the exception and then invoke the main loop again. If an exception is thrown while the framework was being constructed, then construction will fail, and the application may choose to retry creating the framework, maybe with different parameters.

It is recommended to handle exceptions within callbacks whenever possible. Possible means that the callback is actually able to handle the exception and do something meaningful to respond to it. A callback implementation should not blindly catch all exceptions.

Framework vs. Window callbacks

Framework callbacks, also called global callbacks, are registered in tk11::Framework_Parameters. These callbacks are invoked independently of any windows. For example, the global update callback is invoked once per frame and can be used for updating "global" variables, the global aux_render callback can be used for rendering to common textures used by all windows, and the global init callback can be used to create shared Direct3D resources.

Window callbacks are registered in tk11::Window_Parameters. These callbacks are related to the windows for which they are invoked. For example, the update callback is invoked once per frame per window. Some callbacks exist only as window callbacks, because they are only meaningful in the context of a window. Examples of such callbacks are resize, render and all user input callbacks.

For an application with only one rendering window, it is OK to register only window callbacks. An application with multiple windows may have to register a few global callbacks as well in order to initialize and update resources shared by all windows.

Typedef Documentation

typedef boost::function<void()> tk11::Activate_Callback

Callback type for window activation.

See also:: activate

typedef boost::function<void(ID3D11DeviceContext_ptr)> tk11::Aux_Render_Callback

Callback type for auxiliary scene rendering.

See also:: aux_render

typedef boost::function<void(unsigned int)> tk11::Char_Input_Callback

Callback type for character input.

See also:: char_input

typedef boost::function<void()> tk11::Deactivate_Callback

Callback type for window deactivation.

See also:: deactivate

typedef boost::function<void(ID3D11Device_ptr)> tk11::Init_Callback

Callback type for scene initialization.

See also:: init

typedef boost::function<void(unsigned int)> tk11::Key_Down_Callback

Callback type for key press.

See also:: key_down

typedef boost::function<void(unsigned int)> tk11::Key_Repeat_Callback

Callback type for key repeat.

See also:: key_repeat

typedef boost::function<void(unsigned int)> tk11::Key_Up_Callback

Callback type for key release.

See also:: key_up

typedef boost::function<Message_Result(HWND, UINT, WPARAM, LPARAM)> tk11::Message_Callback

Callback type for windows message hook.

See also:: message

typedef boost::optional<LRESULT> tk11::Message_Result

Optional result of window procedure.

This type is used as return type of the message callback, as well as internally in the framework. It optionally holds an LRESULT value to be returned by the window procedure.

A value of not_handled causes DefWindowProc to be called. The window procedure will return the result returned by DefWindowProc

Any other value (e.g. TRUE) will be returned by the window procedure without calling DefWindowProc

The exact meaning of the result value depends on the type of message being handled. If a callback does not handle a certain message, then it should return not_handled.

See also:: not_handled, message

typedef boost::function<void(Mouse_Button, int, int)> tk11::Mouse_Down_Callback

Callback type for mouse button press.

See also:: mouse_move

typedef boost::function<void()> tk11::Mouse_Enter_Callback

Callback type for mouse pointer entering the window.

See also:: mouse_enter

typedef boost::function<void()> tk11::Mouse_Leave_Callback

Callback type for mouse pointer leaving the window.

See also:: mouse_leave

typedef boost::function<void(int, int)> tk11::Mouse_Motion_Callback

Callback type for high precision mouse motion.

See also:: mouse_motion

typedef boost::function<void(int, int)> tk11::Mouse_Move_Callback

Callback type for mouse pointer movement.

See also:: mouse_move

typedef boost::function<void(Mouse_Button, int, int)> tk11::Mouse_Up_Callback

Callback type for mouse button release.

See also:: mouse_move

typedef boost::function<void(int, int, int)> tk11::Mouse_Wheel_Callback

Callback type for mouse wheel motion.

See also:: mouse_wheel

typedef boost::function<void(ID3D11DeviceContext_ptr, ID3D11RenderTargetView_ptr, ID3D11DepthStencilView_ptr)> tk11::Render_Callback

Callback type for scene rendering.

See also:: render

typedef boost::function<void(unsigned int, unsigned int, bool, ID3D11Device_ptr, IDXGISwapChain_ptr, ID3D11Texture2D_ptr)> tk11::Resize_Callback

Callback type for target window resize.

See also:: resize

typedef boost::function<void(const Duration&)> tk11::Update_Callback

Callback type for scene update.

See also:: update

Enumeration Type Documentation

enum tk11::Mouse_Button

Mouse button identifiers.

Enumerator:

left_button	Left mouse button.
middle_button	Middle mouse button.
right_button	Right mouse button.
extra_button1	Extra mouse button #1.
extra_button2	Extra mouse button #2.

Function Documentation

void activate ( )

Callback for window activation (callback).

This callback is invoked whenever a target window is deactivated. Applications can use this callback to start any tasks which are needed only while frames are being rendered. Note that the render and update callbacks are not invoked while the window is deactivated.

See also:: tk11::Message_Callback

void aux_render ( tk11::ID3D11DeviceContext_ptr context )

Callback for auxiliary rendering (callback).

This callback is invoked once per frame for the framework and once again for every window when the framework is ready for rendering to auxiliary targets, such as textures.

The application is responsible for binding render targets before rendering. For rendering the scene to the back buffer, the render callback should be used instead.

Parameters:

context

Interface of Direct3D device context

See also:: tk11::Aux_Render_Callback, render

void char_input ( unsigned int char_ )

Callback for character input(callback).

This callback is invoked when a key has been pressed or repeated. Unlike the key_down, key_repeat and key_up callbacks, this callback receives the key code as an UTF-16 character code, which can be inserted into a string or displayed on the screen.

Parameters:

char_

UTF-16 Character code

See also:: tk11::Char_Input, key_down, key_repeat, key_up

Examples:: input.cpp.

void deactivate ( )

Callback for window deactivation (callback).

This callback is invoked whenever a target window is deactivated. Applications can use this callback to stop any tasks which are not needed while no frames are being rendered. Note that the render and update callbacks are not invoked while the window is deactivated.

See also:: tk11::Message_Callback

void init ( tk11::ID3D11Device_ptr device )

Callback for scene initialization (callback).

This callback is invoked at startup of the framework and possibly again when a lost device has been restored. The application should create all resources from within this callback, replacing or destroying existing resources if necessary.

At startup, this callback is invoked before the resize callback, so if any resources depend on the viewport size, then these resources should be created from within resize.

Parameters:

device

Interface of Direct3D device

See also:: tk11::Init_Callback, Framework

Examples:: cube.cpp, empty.cpp, empty_class.cpp, input.cpp, and torus.cpp.

void key_down ( unsigned int key )

Callback for key press (callback).

This callback is invoked when a key has been pressed. The key is identified by its Windows virtual key code. See the MSDN documentation about virtual key codes.

This callback is not invoked on key repeat. To be notified on key repeat, use the key_repeat callback. If key repeat and initial key press should be handled in the same way, simply bind both callbacks to the same function.

Virtual key codes are not character codes. For character input in UTF-16 format, use the char_input callback.

Parameters:

key

Virtual key code

See also:: tk11::Key_Down_Callback, key_repeat, key_up, char_input

Examples:: input.cpp.

void key_repeat ( unsigned int key )

Callback for key repeat (callback).

This callback is invoked on key repeat, i.e. when a key which is being held down is repeated. The key is identified by its Windows virtual key code. See the MSDN documentation about virtual key codes.

Virtual key codes are not character codes. For character input in UTF-16 format, use the char_input callback.

Parameters:

key

Virtual key code

See also:: tk11::Key_Repeat_Callback, key_down, key_repeat, char_input

Examples:: input.cpp.

void key_up ( unsigned int key )

Callback for key release (callback).

This callback is invoked when a key has been released. The key is identified by its Windows virtual key code. See the MSDN documentation about virtual key codes.

This callback is not invoked on key repeat.

Virtual key codes are not character codes. For character input in UTF-16 format, use the char_input callback.

Parameters:

key

Virtual key code

See also:: tk11::Key_Up_Callback, key_down, key_up, char_input

Examples:: input.cpp.

tk11::Message_Result message	(	HWND	window,
		UINT	message,
		WPARAM	wparam,
		LPARAM	lparam
	)

Callback for windows message hook (callback).

This callback is invoked whenever a window which was created by the Framework has received a message. It can be used by applications to hook into the window procedure and handle messages.

If the callback function does not handle the message it received, it should return tk11::not_handled. Otherwise, the meaning of the return value depends on the type of message being handled. See the documentation of the type tk11::Message_Result for more information.

Note that some types of messages are handled by the framework. If this callback handles such a message (i.e. it returns a result other than tk11::not_handled), then the framework will not handle the message. This may cause certain features of the framework not to function as expected.

The following messages are handled by the framework: WM_CREATE, WM_DESTROY, WM_SIZE, WM_ACTIVATE, WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDOWN, WM_XBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONUP, WM_RBUTTONUP, WM_XBUTTONUP, WM_MOUSEMOVE, WM_INPUT, WM_ENTERMENULOOP, WM_EXITMENULOOP, WM_ENTERSIZEMOVE, WM_EXITSIZEMOVE, WM_MOUSELEAVE, WM_KEYDOWN, WM_KEYUP, WM_CHAR.

Parameters:

	window	Handle of window which received the message
	message	Type of message
	wparam	First parameter
	lparam	Second parameter

Returns:: Optional result of the message, see tk11::Message_Result

See also:: tk11::Message_Callback

void mouse_down	(	tk11::Mouse_Button	button,
		int	x,
		int	y
	)

Callback for mouse button press (callback).

This callback is invoked whenever a mouse button is pressed while the mouse pointer is in the client area of a framework window, or while the mouse is captured.

Parameters:

	button	Button which was pressed
	x	X position of mouse pointer in window client area
	y	Y position of mouse pointer in window client area

See also:: tk11::Mouse_Down_Callback

Examples:: input.cpp.

void mouse_enter ( )

Callback for mouse pointer entering the window (callback).

This callback is invoked when the mouse pointer has entered the visible part of the client area of a framework window.

See also:: tk11::Mouse_Enter_Callback

Examples:: input.cpp.

void mouse_leave ( )

Callback for mouse pointer leaving the window (callback).

This callback is invoked when the mouse pointer has leaves the visible part of the client area of a framework window.

See also:: tk11::Mouse_Leave_Callback

Examples:: input.cpp.

void mouse_motion	(	int	delta_x,
		int	delta_y
	)

Callback for high-precision mouse motion (callback).

This callback is invoked whenever the mouse is moved. It provides relative, unbounded mouse motion data to the application, which is not limited to the screen resolution.

Raw input is read only while the framework window is the active window. Otherwise, raw input is ignored, and this callback is not invoked.

Parameters:

	delta_x	Relative X motion component
	delta_y	Relative Y motion component

See also:: tk11::Mouse_Motion_Callback

Examples:: input.cpp.

void mouse_move	(	int	x,
		int	y
	)

Callback for mouse pointer movement (callback).

This callback is invoked when the mouse pointer was moved over a framework window. The absolute position of the mouse pointer in the window client area are passed to the callback as parameters.

Application should use this callback for tracking the position of the mouse pointer, typically when implementing a GUI with mouse or touch screen input.

If high-precision relative mouse input is needed (e.g. when implementing mouse look in an FPS game), the mouse_motion callback should be used instead.

Parameters:

	x	X position of mouse pointer in window client area
	y	Y position of mouse pointer in window client area

See also:: tk11::Mouse_Move_Callback

Examples:: input.cpp.

void mouse_up	(	tk11::Mouse_Button	button,
		int	x,
		int	y
	)

Callback for mouse button release (callback).

This callback is invoked whenever a mouse button is released while the mouse pointer is in the client area of a framework window, or while the mouse is captured.

Parameters:

	button	Button which was released
	x	X position of mouse pointer in window client area
	y	Y position of mouse pointer in window client area

See also:: tk11::Mouse_Up_Callback

Examples:: input.cpp.

void mouse_wheel	(	int	delta,
		int	x,
		int	y
	)

Callback for mouse wheel movement (callback).

This callback is invoked when the mouse wheel is turned. Its parameters include the relative distance the wheel was moved, as well as the current mouse cursor position.

A positive delta value indicates that the wheel was rotated forward, i.e. away from the user. A negative value indicates that the wheel was rotated backward, i.e. toward the user.

Mouse wheel input is received if and only if the framework window is the active window, regardless whether the mouse cursor is over the client area of the window.

Parameters:

	delta	Mouse wheel delta
	x	X position of mouse pointer in window client area
	y	Y position of mouse pointer in window client area

See also:: tk11::Mouse_Wheel_Callback

Examples:: input.cpp.

void render	(	tk11::ID3D11DeviceContext_ptr	context,
		tk11::ID3D11RenderTargetView_ptr	render_target,
		ID3D11DepthStencilView_ptr	depth_stencil
	)

Callback for scene rendering (callback).

This callback is invoked once per frame when the scene should be rendered to the main render target (the back buffer). The framework binds the back buffer as render target of the immediate context before invocation of this callback. This is done only if a callback has been set.

The application must not change the render target within this callback. For rendering to other targets, such as textures, the application must provide a aux_render callback.

Note that the depth_stencil parameter is a null pointer, unless the window was created with the tk11::Window_Parameters::auto_depth_stencil flag set to true. In this case, the framework takes care of creating a depth buffer, resizing it when needed, and passing an interface to it to the render callback.

Parameters:

	context	Interface of Direct3D device context
	render_target	Interface of render target view
	depth_stencil	Interface of depth/stencil view

See also:: tk11::Render_Callback, aux_render

Examples:: cube.cpp, empty.cpp, empty_class.cpp, input.cpp, and torus.cpp.

void resize	(	unsigned int	x_resolution,
		unsigned int	y_resolution,
		bool	fullscreen,
		tk11::ID3D11Device_ptr	device,
		tk11::IDXGISwapChain_ptr	swap_chain,
		tk11::ID3D11Texture2D_ptr	back_buffer
	)

Callback for target window resize (callback).

This callback is invoked at startup and whenever the size of the target window was changed, or the application has switched between fullscreen and windowed mode.

The application can use this callback to update variables which depend on the current target window size or fullscreen resolution, and to create resources which depend on the back buffer. Note that the framework already takes care of resizing the back buffer and creating a render target view.

The callback parameters

Parameters:

	x_resolution	X resolution of target window (in pixels)
	y_resolution	Y resolution of target window (in pixels)
	fullscreen	`true` if in fullscreen mode, `false` otherwise
	device	Interface of Direct3D device
	swap_chain	Interface of DXGI swap chain
	back_buffer	Interface of back buffer texture

See also:: tk11::Resize_Callback

Examples:: cube.cpp, empty.cpp, empty_class.cpp, input.cpp, and torus.cpp.

void update ( const tk11::Duration & elapsed_time )

Callback for auxiliary rendering (callback).

This callback is invoked once per frame for the framework and once again for every window. The application should use this callback for updating all variables of the scene that change over time.

Parameters:

elapsed_time

Elapsed time since startup