Kanzi  3.9.7
Kanzi Engine API
kanzi::win32::DefaultWin32WGLGraphicsOutput Class Reference

Class that represents the default Win32 WGL graphics output. More...

#include <kanzi/core.ui/platform/graphics_output/win32_wgl/default_win32_wgl_graphics_output.hpp>

Inheritance diagram for kanzi::win32::DefaultWin32WGLGraphicsOutput:
[legend]

Public Member Functions

bool bringToFront () noexcept override
 Schedules to bring a window to front. More...
 
KZ_NO_DISCARD optional< void * > createImage (int target, void *data, int *attributes) noexcept override
 Not implemented on WGL. More...
 
 DefaultWin32WGLGraphicsOutput (const kanzi::win32::DefaultWin32WGLGraphicsOutputProperties &properties)
 Constructor. More...
 
bool destroyImage (void *image) noexcept override
 Not implemented on WGL. More...
 
void displayWindow () noexcept
 Displays and activates the window. More...
 
KZ_NO_DISCARD unsigned int findWindowZOrder () const noexcept
 Finds the z ordering for the active window related to all other windows currently visible. More...
 
void gatherEvents (EventQueue &queue) override
 Amends the given event queue with events received so far. More...
 
virtual KZ_NO_DISCARD optional< SurfaceColorSpacegetColorSpace () const noexcept override
 Gets the color space used by the associated graphics context. More...
 
virtual KZ_NO_DISCARD optional< GraphicsContextAPIgetGraphicsContextAPI () const noexcept override
 Gets the API used by the associated graphics context. More...
 
KZ_NO_DISCARD optional< void * > getNativeContextHandle () const noexcept override
 Gets the associated native GL context handle. More...
 
KZ_NO_DISCARD optional< void * > getNativeDisplayHandle () const noexcept override
 Gets the associated native GL display handle. More...
 
KZ_NO_DISCARD optional< NativeEventHandlegetNativeEventHandle () const noexcept override
 Returns a waitable event handle for this event source, if available. More...
 
KZ_NO_DISCARD optional< void * > getNativeSurfaceHandle () const noexcept override
 Gets the associated native GL surface handle. More...
 
KZ_NO_DISCARD optional< NativeWindowHandle > getNativeWindowHandle () const noexcept override
 Gets the associated window handle. More...
 
KZ_NO_DISCARD GLProcPointer getProcAddress (string_view functionName) noexcept override
 Retrieves the pointer to a GL function. More...
 
virtual KZ_NO_DISCARD optional< SurfaceClientAPIgetSurfaceClientAPI () const noexcept override
 Gets the type of the associated graphics surface. More...
 
KZ_NO_DISCARD Matrix4x4 getTargetTransformation () const noexcept override
 Returns the target transformation. More...
 
KZ_NO_DISCARD optional< unsigned int > getWindowHeight () const noexcept override
 Returns the height of the active window. More...
 
KZ_NO_DISCARD optional< int > getWindowPositionX () const noexcept override
 Returns the x position of a window. More...
 
KZ_NO_DISCARD optional< int > getWindowPositionY () const noexcept override
 Returns the y position of a window. More...
 
KZ_NO_DISCARD optional< string > getWindowTitle () const noexcept override
 Gets the title of the window. More...
 
KZ_NO_DISCARD optional< unsigned int > getWindowWidth () const noexcept override
 Returns the width of the active window. More...
 
bool hideWindow () noexcept override
 Schedules to make a window invisible. More...
 
void logClientWindowSize () const noexcept
 Prints the active client window size to log. More...
 
void logDisplayCount () const noexcept
 Prints the number of active displays in the current session. More...
 
void logMousePosition () const noexcept
 Prints the active mouse position to log. More...
 
void logWindowPosition () const noexcept
 Prints the active window position to log. More...
 
void logWindowSize () const noexcept
 Prints the active window size to log. More...
 
bool makeCurrent () noexcept override
 Activates the WGL context for the current thread. More...
 
bool makeFullscreen () noexcept override
 Schedules to make a window full-screen. More...
 
bool makeMaximized () noexcept override
 Schedules to maximize a window. More...
 
bool makeMinimized () noexcept override
 Schedules to minimize a window. More...
 
bool makeRegular () noexcept override
 Schedules to make a window regular. More...
 
bool moveWindow (int positionX, int positionY) noexcept override
 Schedules a window move. More...
 
bool releaseCurrent () noexcept override
 Deactivates the WGL context for the current thread. More...
 
bool resize (unsigned int width, unsigned int height) noexcept override
 Schedules a resize of the target layout area. More...
 
bool resizeWindow (unsigned int width, unsigned int height) noexcept override
 Schedules the resizing of the active window. More...
 
bool setWindowTitle (string_view title) noexcept override
 Sets the title of the window. More...
 
bool showWindow () noexcept override
 Schedules to make a window visible. More...
 
bool swapBuffers () noexcept override
 Posts rendering results. More...
 
bool swapInterval (int interval) noexcept override
 Sets the minimum number of displayed video frames before a buffer swap. More...
 
void updateWindow () noexcept
 Updates the client area of the window. More...
 
 ~DefaultWin32WGLGraphicsOutput ()
 Destructor. More...
 
- Public Member Functions inherited from kanzi::GraphicsOutput
KZ_NO_DISCARD Vector2 getDpi () const noexcept
 Returns the resolution of the target coordinate system in dots per inch. More...
 
KZ_NO_DISCARD unsigned int getHeight () const noexcept
 Returns the height of layout area in the target coordinate system. More...
 
KZ_NO_DISCARD unsigned int getWidth () const noexcept
 Returns the width of layout area in the target coordinate system. More...
 
virtual ~GraphicsOutput ()=default
 Destructor. More...
 
- Public Member Functions inherited from kanzi::EventSource
virtual ~EventSource ()=default
 Destructor. More...
 
- Public Member Functions inherited from kanzi::GLGraphicsOutput
virtual ~GLGraphicsOutput ()=default
 Destructor. More...
 
- Public Member Functions inherited from kanzi::WindowedGraphicsOutput
virtual ~WindowedGraphicsOutput ()=default
 Destructor. More...
 

Protected Member Functions

bool recallWindowPlacement () noexcept
 Restores the position and size of the previously stored window. More...
 
void setTargetTransformation (Matrix4x4 targetTransformation) noexcept
 Sets the target transformation. More...
 
bool storeWindowPlacement () noexcept
 Stores the position and size of the current window. More...
 
void updateTargetLayoutArea () noexcept
 Updates the render target size for the client window. More...
 
- Protected Member Functions inherited from kanzi::GraphicsOutput
void updateDpi (Vector2 dpi)
 Updates the target layout area resolution. More...
 
void updateSize (unsigned int width, unsigned int height)
 Updates the target layout area size. More...
 

Additional Inherited Members

- Public Types inherited from kanzi::GLGraphicsOutput
using GLProcPointer) = void(*)(
 Pointer to GL function. More...
 

Detailed Description

Class that represents the default Win32 WGL graphics output.

Since
Kanzi 3.9.7

Examples

To resize the windowed graphics output:

const auto TargetWindowWidth{ 300u };
const auto TargetWindowHeight{ 200u };
if (getGraphicsOutput()->getWidth() == TargetWindowWidth && getGraphicsOutput()->getHeight() == TargetWindowHeight)
{
// Resize complete.
quit();
return;
}
auto wgo = getGraphicsOutput<WindowedGraphicsOutput>(0);
if (!wgo)
{
// Resize not supported.
quit();
return;
}
// Schedule resize.
auto success = wgo->resize(TargetWindowWidth, TargetWindowHeight);
if (!success)
{
// Resize not supported.
quit();
return;
}
quit();

To set a position for the windowed graphics output:

const auto TargetWindowPositionX{ 200 };
const auto TargetWindowPositionY{ 100 };
auto wgo = getGraphicsOutput<WindowedGraphicsOutput>(0);
if (!wgo)
{
// Move not supported.
quit();
return;
}
auto posX = wgo->getWindowPositionX();
auto posY = wgo->getWindowPositionY();
if (!posX || !posY)
{
// Move not supported.
quit();
return;
}
if (*posX == TargetWindowPositionX && *posY == TargetWindowPositionY)
{
// Move complete.
quit();
return;
}
// Schedule move.
auto success = wgo->moveWindow(TargetWindowPositionX, TargetWindowPositionY);
if (!success)
{
// Move not supported.
quit();
return;
}
quit();

To set a title for the windowed graphics output:

const string TargetWindowTitle{ "Window Title Test" };
auto wgo = getGraphicsOutput<WindowedGraphicsOutput>(0);
if (!wgo)
{
// Window titles not supported.
quit();
return;
}
auto title = wgo->getWindowTitle();
if (!title)
{
// Window titles not supported.
quit();
return;
}
if (*title == TargetWindowTitle)
{
// Title setting complete.
quit();
return;
}
// Schedule setting of window title.
auto success = wgo->setWindowTitle(TargetWindowTitle);
if (!success)
{
// Window titles not supported.
quit();
return;
}
quit();

To show and hide the windowed graphics output:

auto wgo = getGraphicsOutput<WindowedGraphicsOutput>(0);
if (!wgo)
{
// Show and hide not supported.
quit();
return;
}
EXPECT_NO_FATAL_FAILURE(wgo->hideWindow());
EXPECT_NO_FATAL_FAILURE(wgo->showWindow());
quit();

To minimize and maximize the windowed graphics output:

auto wgo = getGraphicsOutput<WindowedGraphicsOutput>(0);
if (!wgo)
{
// Minimize and maximize not supported.
quit();
return;
}
EXPECT_NO_FATAL_FAILURE(wgo->makeMinimized());
EXPECT_NO_FATAL_FAILURE(wgo->makeMaximized());
quit();

To bring the windowed graphics output to front:

auto wgo = getGraphicsOutput<WindowedGraphicsOutput>(0);
if (!wgo)
{
// Bring to front not supported.
quit();
return;
}
EXPECT_NO_FATAL_FAILURE(wgo->bringToFront());
quit();

Constructor & Destructor Documentation

kanzi::win32::DefaultWin32WGLGraphicsOutput::DefaultWin32WGLGraphicsOutput ( const kanzi::win32::DefaultWin32WGLGraphicsOutputProperties properties)
explicit

Constructor.

Parameters
propertiesSpecifies properties to request for the graphics output.
kanzi::win32::DefaultWin32WGLGraphicsOutput::~DefaultWin32WGLGraphicsOutput ( )

Destructor.

Member Function Documentation

void kanzi::win32::DefaultWin32WGLGraphicsOutput::logDisplayCount ( ) const
noexcept

Prints the number of active displays in the current session.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::logClientWindowSize ( ) const
noexcept

Prints the active client window size to log.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::logWindowSize ( ) const
noexcept

Prints the active window size to log.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::logWindowPosition ( ) const
noexcept

Prints the active window position to log.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::logMousePosition ( ) const
noexcept

Prints the active mouse position to log.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::updateWindow ( )
noexcept

Updates the client area of the window.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::displayWindow ( )
noexcept

Displays and activates the window.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::gatherEvents ( EventQueue queue)
overridevirtual

Amends the given event queue with events received so far.

Parameters
queueEvent queue to update. Do not clear and do not assume that the queue is empty.

Implements kanzi::EventSource.

KZ_NO_DISCARD optional<NativeEventHandle> kanzi::win32::DefaultWin32WGLGraphicsOutput::getNativeEventHandle ( ) const
overridevirtualnoexcept

Returns a waitable event handle for this event source, if available.

Return values
nulloptGetting the event handle failed.
Returns
The native event handle.

Implements kanzi::EventSource.

KZ_NO_DISCARD GLProcPointer kanzi::win32::DefaultWin32WGLGraphicsOutput::getProcAddress ( string_view  functionName)
overridevirtualnoexcept

Retrieves the pointer to a GL function.

Parameters
functionNameName of the GL function.
Returns
Pointer to the function. If not found, null.

Implements kanzi::GLGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::makeCurrent ( )
overridevirtualnoexcept

Activates the WGL context for the current thread.

Returns
On success, true, otherwise false.

Implements kanzi::GLGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::releaseCurrent ( )
overridevirtualnoexcept

Deactivates the WGL context for the current thread.

Returns
On success, true, otherwise false.

Implements kanzi::GLGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::swapBuffers ( )
overridevirtualnoexcept

Posts rendering results.

Implicitly flushes the rendering pipeline and executes all received rendering commands before posting.

Returns
On success, true, otherwise false.

Implements kanzi::GLGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::swapInterval ( int  interval)
overridevirtualnoexcept

Sets the minimum number of displayed video frames before a buffer swap.

Parameters
intervalMinimum number of video frames to wait before buffer swap.
Returns
On success, true, otherwise false.

Implements kanzi::GLGraphicsOutput.

KZ_NO_DISCARD optional<void*> kanzi::win32::DefaultWin32WGLGraphicsOutput::getNativeDisplayHandle ( ) const
overridevirtualnoexcept

Gets the associated native GL display handle.

Return values
nulloptGetting the GL display failed.
Returns
The handle of the associated display object.

Implements kanzi::GLGraphicsOutput.

KZ_NO_DISCARD optional<void*> kanzi::win32::DefaultWin32WGLGraphicsOutput::getNativeContextHandle ( ) const
overridevirtualnoexcept

Gets the associated native GL context handle.

Return values
nulloptGetting the GL context failed.
Returns
The handle of the associated graphics context object.

Implements kanzi::GLGraphicsOutput.

KZ_NO_DISCARD optional<void*> kanzi::win32::DefaultWin32WGLGraphicsOutput::getNativeSurfaceHandle ( ) const
overridevirtualnoexcept

Gets the associated native GL surface handle.

Return values
nulloptGetting the GL surface failed.
Returns
The handle of the associated surface object.

Implements kanzi::GLGraphicsOutput.

KZ_NO_DISCARD optional<void*> kanzi::win32::DefaultWin32WGLGraphicsOutput::createImage ( int  target,
void *  data,
int *  attributes 
)
overridevirtualnoexcept

Not implemented on WGL.

Returns
Nullopt.
See also
destroyImage().

Implements kanzi::GLGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::destroyImage ( void *  image)
overridevirtualnoexcept

Not implemented on WGL.

Returns
False.

Implements kanzi::GLGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::resize ( unsigned int  width,
unsigned int  height 
)
overridevirtualnoexcept

Schedules a resize of the target layout area.

Parameters
widthNew target layout area width in pixels.
heightNew target layout area height in pixels.
Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::setWindowTitle ( string_view  title)
overridevirtualnoexcept

Sets the title of the window.

Parameters
titleThe title to set.
Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

KZ_NO_DISCARD optional<string> kanzi::win32::DefaultWin32WGLGraphicsOutput::getWindowTitle ( ) const
overridevirtualnoexcept

Gets the title of the window.

Return values
nulloptGetting the title of the window failed.
Returns
The title of the window.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::resizeWindow ( unsigned int  width,
unsigned int  height 
)
overridevirtualnoexcept

Schedules the resizing of the active window.

Parameters
widthNew window width in implementation defined units.
heightNew window height in implementation defined units.
Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

KZ_NO_DISCARD optional<unsigned int> kanzi::win32::DefaultWin32WGLGraphicsOutput::getWindowWidth ( ) const
overridevirtualnoexcept

Returns the width of the active window.

Return values
nulloptFailed to get the width of the active window.
Returns
Width of the active window in implementation-defined units.

Implements kanzi::WindowedGraphicsOutput.

KZ_NO_DISCARD optional<unsigned int> kanzi::win32::DefaultWin32WGLGraphicsOutput::getWindowHeight ( ) const
overridevirtualnoexcept

Returns the height of the active window.

Return values
nulloptFailed to get the height of the active window.
Returns
Height of the active window in implementation-defined units.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::moveWindow ( int  positionX,
int  positionY 
)
overridevirtualnoexcept

Schedules a window move.

Parameters
positionXNew x position of the window in implementation-defined units.
positionYNew y position of the window in implementation-defined units.
Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

KZ_NO_DISCARD optional<int> kanzi::win32::DefaultWin32WGLGraphicsOutput::getWindowPositionX ( ) const
overridevirtualnoexcept

Returns the x position of a window.

Return values
nulloptFailed to get the x position of the window.
Returns
X position of the window in implementation-defined units.

Implements kanzi::WindowedGraphicsOutput.

KZ_NO_DISCARD optional<int> kanzi::win32::DefaultWin32WGLGraphicsOutput::getWindowPositionY ( ) const
overridevirtualnoexcept

Returns the y position of a window.

Return values
nulloptFailed to get the y position of the window.
Returns
Y position of the window in implementation-defined units.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::makeFullscreen ( )
overridevirtualnoexcept

Schedules to make a window full-screen.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::makeRegular ( )
overridevirtualnoexcept

Schedules to make a window regular.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::makeMaximized ( )
overridevirtualnoexcept

Schedules to maximize a window.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::makeMinimized ( )
overridevirtualnoexcept

Schedules to minimize a window.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::showWindow ( )
overridevirtualnoexcept

Schedules to make a window visible.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::hideWindow ( )
overridevirtualnoexcept

Schedules to make a window invisible.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::bringToFront ( )
overridevirtualnoexcept

Schedules to bring a window to front.

Returns
On success, true, otherwise false.

Implements kanzi::WindowedGraphicsOutput.

KZ_NO_DISCARD unsigned int kanzi::win32::DefaultWin32WGLGraphicsOutput::findWindowZOrder ( ) const
noexcept

Finds the z ordering for the active window related to all other windows currently visible.

Returns
The Z ordering.
KZ_NO_DISCARD Matrix4x4 kanzi::win32::DefaultWin32WGLGraphicsOutput::getTargetTransformation ( ) const
overridevirtualnoexcept

Returns the target transformation.

Returns
Target transformation matrix.

Implements kanzi::GLGraphicsOutput.

virtual KZ_NO_DISCARD optional<GraphicsContextAPI> kanzi::win32::DefaultWin32WGLGraphicsOutput::getGraphicsContextAPI ( ) const
overridevirtualnoexcept

Gets the API used by the associated graphics context.

Return values
nulloptFailed to get the graphics context.
Returns
The associated graphics context API.

Implements kanzi::GLGraphicsOutput.

virtual KZ_NO_DISCARD optional<SurfaceClientAPI> kanzi::win32::DefaultWin32WGLGraphicsOutput::getSurfaceClientAPI ( ) const
overridevirtualnoexcept

Gets the type of the associated graphics surface.

Return values
nulloptFailed to get the graphics surface.
Returns
The type of the associated graphics surface.

Implements kanzi::GLGraphicsOutput.

virtual KZ_NO_DISCARD optional<SurfaceColorSpace> kanzi::win32::DefaultWin32WGLGraphicsOutput::getColorSpace ( ) const
overridevirtualnoexcept

Gets the color space used by the associated graphics context.

Return values
nulloptFailed to get the color space.
Returns
The color space used by the associated graphics context.

Implements kanzi::GLGraphicsOutput.

KZ_NO_DISCARD optional<NativeWindowHandle> kanzi::win32::DefaultWin32WGLGraphicsOutput::getNativeWindowHandle ( ) const
overridevirtualnoexcept

Gets the associated window handle.

Return values
nulloptFailed to get handle for the associated window.
Returns
The handle for the native window.

Implements kanzi::WindowedGraphicsOutput.

void kanzi::win32::DefaultWin32WGLGraphicsOutput::updateTargetLayoutArea ( )
protectednoexcept

Updates the render target size for the client window.

bool kanzi::win32::DefaultWin32WGLGraphicsOutput::storeWindowPlacement ( )
protectednoexcept

Stores the position and size of the current window.

Returns
On success, true, otherwise false.
bool kanzi::win32::DefaultWin32WGLGraphicsOutput::recallWindowPlacement ( )
protectednoexcept

Restores the position and size of the previously stored window.

Returns
On success, true, otherwise false.
void kanzi::win32::DefaultWin32WGLGraphicsOutput::setTargetTransformation ( Matrix4x4  targetTransformation)
inlineprotectednoexcept

Sets the target transformation.

Parameters
targetTransformationThe target transformation matrix.

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