Windows
[Framework]
|
Classes | |
| class | tk11::Window |
| Direct3D Rendering window. More... | |
Detailed Description
Once the framework has been initialized, the application can create one or more windows.
This is done by creating instances of tk11::Window. Before a winow can be created, the application must set up a tk11::Window_Parameters structure, which contains creation parameters and callbacks for the new window. Also, every window is tied to a framework, so the application must provide a reference to the tk11::Framework object when constructing a tk11::Window object.
Attention: Some callbacks, such as init and resize, will be called while the window is being constructed. If these callbacks access any other resources or variables of the application, make sure these are initialized before the tk11::Window object is constructed. If the window object is a member of a class, it is good practice to make sure it is constructed after any other members (by declaring members in the order they should be constructed).
A window may be destroyed again at any time by destroying its tk11::Window object. However, the framework must not be destroyed before all windows have been destroyed.
The user may close a window by clicking on the close button or pressing ALT+F4. In this case, the tk11::Window object stays alive nevertheless, until the application destroys it. A window closed in this way can not be reopened. Instead, the application must create a new window.
The main loop of the framework exits when all windows have been destroyed. It is possible that the main window is destroyed before any additional windows, if the user closes the main window first.
Render Targets
Each tk11::Window object automatically creates a swap chain for the window and a render target view of the back buffer of the swap chain. An interface to this render target view (tk11::ID3D11RenderTargetView_ptr) is passed to the render callback of each window.
Optionally, a tk11::Window object may also create a depth/stencil buffer and a corresponding depth stencil view (tk11::ID3D11DepthStencilView_ptr). By default, no depth/stencil buffer is created. The application can change this behavior by setting the tk11::Window_Parameters::auto_depth_stencil flag and, optionally, the tk11::Window_Parameters::auto_depth_stencil_format parameter. The depth/stencil buffer is automatically recreated whenever the window is resized. It is automatically bound to the output merger when the render callback is invoked, and an interface is also passed to the render callback. The torus::cpp example demonstrates how to use depth buffers.
Note that when rendering to targets other than the main render target (which applications should do in the aux_render callback), then the application is fully responsible for creating a suitable depth buffer if one is needed. The function tk11::create_depth_stencil_view_2d can be used for this purpose, as well as other utilities in the Render Targets group.
Window Deactivation
A framework window may be deactivated, for example by minimizing the window or activating another window. While the window is deactivated, tk11::Framework::frame will still handle window messages for the window, but not present any frames and not invoke the update, aux_render and render callbacks. If all windows are inactive, then the frame() method is idle while no windows messages are being processed, consuming no CPU cycles.
It is possible to control exactly when a window is deactivated by setting the tk11::Window_Parameters::active_condition parameter. By default, a window is deactivated whenever it is minimized. See the documentation of the tk11::Active_Condition type for other possible settings.
Note that a window will always be deactivated when its menu is active and while the user is dragging or resizing the window.
Each window has a separate window clock, which is paused while the window is deactivated. This allows applications to use the elapsed_time parameter of the update callback without having to consider window deactivation. When a window is deactivated, time simply stops (and so will all animations computed from this time base), and when the window is activated again, time resumes at the point it was stopped, thus preventing large jumps in animations and simulations. See Time and Clocks for more information, in particular the documentation of the tk11::Secondary_Clock class.
Note that in an application with multiple windows, this means that the update callback of each window may be called with a different elapsed_time value. If an application also needs a global time base, then it should register a global update callback at the framework (by specifying tk11::Framework_Parameters::update_callback). This callback receives its elapsed_time value from the main clock of the framework. The main clock is paused if and only if all windows are inactive.
Mouse Cursor
By default, the standard arrow mouse cursor is shown over every target window in both windowed and fullscreen mode. If an application does not need a mouse cursor, or it renders its own mouse cursor in Direct3D 11, or it needs a mouse cursor other than an arrow, then the parameter tk11::Window_Parameters::cursor_mode must be set. For possible options, see the tk11::Cursor_Mode enum type.
The default cursor mode is tk11::Framework::standard_cursor. This causes the arrow cursor to be shown all the time.
In tk11::Framework::hide_cursor mode, the Windows mouse cursor is completely hidden whenever it is over the visible part of the client area of the window. As long as the mouse cursor is outside the client area, it is shown as usual. In fullscreen mouse, the Windows mouse cursor is always invisible. This is the preferred mode for applications which render the mouse cursor in Direct3D or do not need a mouse cursor at all.
In tk11::Framework::manual_cursor mode, the framework does not make any changes to the cursor at all. The application must set an appropriate cursor whenever the mouse enters the client area of the window. For this purpose, an application will typically register the mouse_enter callback and call the Windows function SetCursor within the callback. For more information, see the MSDN documentation of the SetCursor function.
It is not necessary to reset the mouse cursor when it leaves the client area of the window. The nonclient area of the window, as well as windows of other applications, should take care of settig the cursor appearance themselves.
