Display (`pmma.Display`)#

This class is responsible for managing the display window, including its creation, configuration, and properties. It provides methods to manipulate the window’s state, such as minimizing, maximizing, and setting its position. Additionally, it offers functionality to retrieve information about the display, such as its size, aspect ratio, and frame rate.

Create#

class pmma.Display → pmma.Display#: This creates a new Display object.

Note

This does not create the actual window. You must call the create() method to create the window.

Methods#

Display.create(size: npt.NDArray[np.int32] | npt.NDArray[np.int8] | npt.NDArray[np.int16] | npt.NDArray[np.int64] | Iterable[int] = np.array([0, 0], dtype=np.uint32, order='C'), caption: str = 'PMMA Display', fullscreen: None | bool = None, resizable: bool = False, no_frame: bool = False, vsync: bool = False, icon: str = '', centered: bool = True, maximized: bool = False, transparent: bool = False) → None#

This method is used to create a window which will be the rendering target for PMMA. All 2D and 3D content will end up being rendered to this window.

Parameters:

size (Union[npt.NDArray[np.int32], npt.NDArray[np.int8], npt.NDArray[np.int16], npt.NDArray[np.int64], Iterable[int]]) – The size of the window in pixels. If set to (0, 0) the window will be created at the current monitor’s resolution and be automatically full-screen. For this method you can input either an iterable Python sequence (list or tuple for example) or a numpy array. All inputs are converted automatically to be a continuous uint32 (or unsigned int 32) numpy array - its unlikely this conversion will be slow in this scenario.
caption (str) – The window title name.
fullscreen (Union[None, bool]) – This is used to control if the window should be full screen or not. If the value is left as the default None PMMA will set the window to be automatically full screened when the window size is (0, 0).
resizable (bool) – This is used to control whether the window can be resized by the user. By default the end user cannot resize the window.
no_frame (bool) – This is used to control whether the window has a border and title bar visible. Please note that when no title bar is visible it can be harder for the user to re-position the window. By default the window is set to have a frame.
vsync (bool) – This is used to determine if the window refresh rate will be synchronized with the current monitor refresh rate. This is by default set to True as this can improve application efficiency and reduce visual tearing.
icon (str) – This is used to set the window icon. You should enter a valid file path here. If left as the default empty string, the default PMMA display icon is used.
centered (bool) – This is used to set the window to be centered in the currently active window when created. The currently active window is typically the one the mouse cursor is in when the window is created. This defaults to True ensuring the window is centered on screen. This does not prevent the window from being moved later on.
maximized (bool) – This is used to determine if the window should be considered as being in a maximized state. The default value here is True.

Note

This method must be called before any rendering can occur.

Note

Certain display settings can only be set at the time of window creation. If you need to change these settings, you will need to recreate the window. We are working on making this process easier.

Note

Only one PMMA display can be created at a time. You can have multiple display instances but they will all share the same object behind the scenes. This is something we are looking to address in a future version of PMMA.

Display.center_window() → None#: This method is used to position the window centrally in the monitor the window was first created on.

Note

We are working on a way to have this center the window to whichever monitor it is currently on.

Warning

A valid window must be created using Display.Create before calling this method.

Display.clear() → None#: This method is used to clear all rendered graphics from the previous frame, and also used to apply the specified background color defined in Display.window_fill_color.

Note

This method must be called from the same thread that the window was created in.

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_window_in_focus() → None#: This method is used to force the created window to be put into focus.

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_window_minimized(value: bool) → None#

This method is used to minimize the created window (to the taskbar or equivalent on your operating system).

Parameters:: value (bool) – When True the display will be minimized. When False the display will be returned to its original state (not maximized).

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_window_maximized(value: bool) → None#

This method is used to maximize the created window to fill the current monitor, showing the title bar.

Parameters:: value (bool) – When True the display will be maximized. When False the display will be returned to its original state (not minimized).

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_icon(icon_path: str) → None#

This method is used to pass an image file path to the display to be used as an icon, which replaces the default icon.

Parameters:: icon_path (str) – This is used to set the window icon. You should enter a valid file path here. If left as the default empty string, the default PMMA display icon is used.

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_caption(caption: str) → None#

This method is used to pass a string to use as the display caption.

Parameters:: caption (str) – The window title name.

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_relative_window_position(position: npt.NDArray[np.int32] | npt.NDArray[np.int8] | npt.NDArray[np.int16] | npt.NDArray[np.int64] | Iterable[int]) → None#

This method is used to set the window to be positioned on-screen relative to the origin of the current monitor (the top left corner).

Parameters:: position (Union[npt.NDArray[np.int32], npt.NDArray[np.int8], npt.NDArray[np.int16], npt.NDArray[np.int64], Iterable[int]]) – The number of pixels to move the window to. This takes two values (x, y).

Warning

A valid window must be created using Display.Create before calling this method.

Display.set_absolute_window_position(position: npt.NDArray[np.int32] | npt.NDArray[np.int8] | npt.NDArray[np.int16] | npt.NDArray[np.int64] | Iterable[int]) → None#

This method is used to set the window to be positioned on-screen relative to the windowing system’s origin (typically the top left corner of the left-most monitor as arranged on your desktop).

Parameters:: position (Union[npt.NDArray[np.int32], npt.NDArray[np.int8], npt.NDArray[np.int16], npt.NDArray[np.int64], Iterable[int]]) – The number of pixels to move the window to. This takes two values (x, y).

Note

Please be aware that some monitor layouts will have ‘gaps’ between each monitor due to their arrangement or resolution. Care should be taken to not place the window in this area as it will not be seen.

Warning

A valid window must be created using Display.Create before calling this method.

Display.refresh(min_refresh_rate: int = 5, max_refresh_rate: Union[None, int]: None, limit_refresh_rate: bool = True, lower_refresh_rate_on_minimize: bool = True, lower_refresh_rate_on_focus_loss: bool = True, lower_refresh_rate_on_low_battery: bool = True) → None#

This method is used to update the window to show all the content rendered since Display.clear. Additionally, it is used to limit the refresh rate of the window to avoid excessive resource usage.

When the window is created with vsync=True the refresh rate of the window will be forced to the monitor refresh rate. Otherwise, the refresh rate will be dynamically adjusted to save resources. This behaviour is customizable using the parameters below.

Parameters:

min_refresh_rate (int) – The minimum refresh rate to dynamically adjust down to. If this value is 0, then the display will be updated only when nessasary (most efficient), this will not break window functionality.
max_refresh_rate (Union[int, None]) – The maximum refresh rate to dynamically adjust up to. There is no guarantee this value will be achieved - but the window should not refresh at a faster rate for extended period of times. If set to None the window refresh rate will be capped at either 60 when not using vsync, or allowed to run up to the vsync limit.
limit_refresh_rate (bool) – This is used to completely disable any dynamic refresh rate behaviour and force the window to refresh as fast as possible. This is not recommended for most use-cases, but could be useful for performance testing.
lower_refresh_rate_on_minimize (bool) – This is used to customize the dynamic refresh rate behaviour. If True then when the window is minimized the refresh rate of the window will drop. If False the refresh rate of the window will not change when the window is minimized.
lower_refresh_rate_on_focus_loss (bool) – This is used to customize the dynamic refresh rate behaviour. If True then when the window is not in focus the refresh rate of the window will drop. If False the refresh rate of the window will not change when the window is not in focus.
lower_refresh_rate_on_low_battery (bool) – This is used to customize the dynamic refresh rate behaviour. If True then when the device is in a ‘low power state’ the refresh rate of the window will drop. If False the refresh rate of the window will not change when the device is in a ‘low power state’.

Note

If you set min_refresh_rate to 0, the display will be refreshed when the user interacts with it or when the rendered content on-screen changes. This created a highly-efficient behaviour seen in most desktop applications and is generally recommended.

Note

This method must be called from the same thread that the window was created in.

Warning

A valid window must be created using Display.Create before calling this method.

Display.trigger_event_refresh() → None#: This method is used to force the window to refresh. This works even when min_refresh_rate is 0.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_caption() → str#

This method is used to get the window caption.

Returns str:: The window caption as a string.

Display.get_center() → npt.NDArray[np.int32] | npt.NDArray[np.int8] | npt.NDArray[np.int16] | npt.NDArray[np.int64] | Iterable[int]#

This method is used to get the center point of the window.

Returns Union[npt.NDArray[np.int32], npt.NDArray[np.int8],npt.NDArray[np.int16],npt.NDArray[np.int64],Iterable[int]]:: The center point as a coordinate (x, y).

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_aspect_ratio() → float#

This method is used to get the aspect ratio of the window.

Returns float:: The window aspect ratio. For example: 2.667 would be returned for a window with aspect ration 16:9.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_frame_rate() → int#

This method is used to get the current frame rate of the window.

Returns int:: The refresh rate of the window.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_frame_time() → float#

This method is used to get the current frame time of the window.

Returns float:: The time in seconds between the current and previous frame.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_width() → int#

This method gets the current window width in pixels.

Returns int:: The window width in pixels.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_height() → int#

This method gets the current window height in pixels.

Returns int:: The window height in pixels.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_size() → npt.NDArray[np.int32] | npt.NDArray[np.int8] | npt.NDArray[np.int16] | npt.NDArray[np.int64] | Iterable[int]#

This method gets the current size of the window in pixels (width, height)

Returns Union[npt.NDArray[np.int32], npt.NDArray[np.int8],npt.NDArray[np.int16],npt.NDArray[np.int64],Iterable[int]]:: The size of the window in pixels.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_msaa_samples() → int#

This method is used to get the number of Multi-Sample Anti-Aliasing samples.

Returns int:: The number of samples.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_current_monitor_refresh_rate() → int#

This method gets the refresh rate of the current monitor video mode.

Returns int:: The current monitor video mode refresh rate.

Warning

A valid window must be created using Display.Create before calling this method.

Display.toggle_full_screen() → None#: This method is used to switch the window between full screen and windowed modes.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_in_focus() → bool#

This method is used to get if the window is currently in focus.

Returns bool:: Returns True when in focus. Returns False when not in focus.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_minimized() → bool#

This method is used to get if the window is currently minimized.

Returns bool:: Returns True when the window is minimized. Returns False when the window is not minimized.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_maximized() → bool#

This method is used to get if the window is currently maximized.

Returns bool:: Returns True when the window is maximized. Returns False when the window is not maximized.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_resizable() → bool#

This method is used to get if the window is resizable.

Returns bool:: Returns True when the window is able to be resized by the end user. Returns False when the window is not resizable by the end user.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_visible() → bool#

This method is used to get if the window is currently visible on-screen.

Returns bool:: Returns True when the window is visible. Returns False when the window is not visible.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_always_on_top() → bool#

This method is used to get if the window is set to be always on top.

Returns bool:: Returns True when the window is always on top. Returns False when the window is not always on top.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_using_vsync() → bool#

This method is used to get if the window is set to use vsync. Note that this does not check if vsync is supported in your setup, as this varies based on third party factors that we cannot check.

Returns bool:: Returns True when vsync is used. Returns False when the window is not using vsync.

Warning

A valid window must be created using Display.Create before calling this method.

Display.is_window_auto_minimized() → bool#

This method is used get if the window is set to automatically minimize when it is no longer in focus. This is typically seen in game applications.

Returns bool:: Returns True when the window is configured to automatically minimize when focus is lost. Returns False when the window is not configured to automatically minimize when focus is lost.

Warning

A valid window must be created using Display.Create before calling this method.

Display.get_orthographic_projection() → npt.NDArray[np.float32] | npt.NDArray[np.float16] | npt.NDArray[np.float64] | Iterable[float]#

This method is used to get the display's orthographic projection.

Returns Union[npt.NDArray[np.float32], npt.NDArray[np.float16], npt.NDArray[np.float64], Iterable[float]]:: The projection matrix.

Warning

A valid window must be created using Display.Create before calling this method.

Attributes#

Display.window_fill_color#: Used to control the background color of the window.

Display (pmma.Display)#

Create#

Methods#

Attributes#

Display (`pmma.Display`)#