WindowProxy – vkframes

type, public :: WindowProxy

A window showing a scene (see the module documentation).

Inherits

Help

Components

Type	Visibility	Attributes		Name		Initial
real(kind=wp),	private		::	background(3)	=	[0.0_wp, 0.0_wp, 0.0_wp]	background color [r, g, b] (0 to 1)
logical,	private		::	camera_throw_	=	.true.	the camera keeps moving after a drag released while moving
type(SimulationClock),	private		::	clock_			the window's simulation clock
integer,	private		::	current	=	0	number of views; the current one (0: none)
logical,	private		::	default_keys_	=	.true.	the built-in keys on
type(View),	private		::	default_view			used when there are no views
class(DragHandle),	private,	pointer	::	dragged_handle	=>	null()	the handle grabbed (not owned)
type(CameraFlight),	private		::	flight			the camera flight (when active)
real(kind=wp),	private		::	fps_	=	0.0_wp	frames per second (the last count's)
real(kind=wp),	private		::	frame_ms_	=	0.0_wp	milliseconds between frames (the last count's)
class(WindowEventHandler),	private,	pointer	::	handler	=>	null()	the program's event handler (not owned)
integer,	private		::	height_	=	1	logical size (for the views' aspect ratio)
logical,	private		::	hosted	=	.false.	in a host's window (its size from resize)
class(DragHandle),	private,	pointer	::	hovered_handle	=>	null()	the handle under the cursor (not owned)
type(HUDEntry),	private,	allocatable	::	huds(:)			the HUD texts shown (first n_huds used)
real(kind=wp),	private		::	last_frame_ms	=	0.0_wp	the last frame()'s duration (ms)
real(kind=wp),	private		::	light_ambient_(3)	=	0.2_wp	[r, g, b]
real(kind=wp),	private		::	light_diffuse_(3)	=	1.0_wp	[r, g, b]
logical,	private		::	light_on	=	.true.	the window's light enabled (no frame's light source)
real(kind=wp),	private		::	light_position_(4)	=	[0.0_wp, 0.0_wp, 1.0_wp, 0.0_wp]	eye coordinates (w 0: directional)
real(kind=wp),	private		::	light_specular_(3)	=	0.0_wp	[r, g, b]
integer,	private		::	n_huds	=	0	number of HUD texts
integer,	private		::	n_views	=	0	number of views; the current one (0: none)
real(kind=wp),	private		::	pixel_ratio_	=	1.0_wp	framebuffer pixels per window unit (a host's window)
integer,	private		::	rate_frames	=	0	frames since then
real(kind=wp),	private		::	rate_start	=	-1.0_wp	the wall time the frames are counted from (s; -1: none)
real(kind=wp),	private		::	record_fps	=	30.0_wp	the video's frames per second
integer(kind=int64),	private		::	record_frames	=	0_int64	frames drawn while recording
real(kind=wp),	private		::	record_wall	=	0.0_wp	the wall time at the start (s)
logical,	private		::	recording_	=	.false.	recording (start_recording)
logical,	private		::	running	=	.false.	open, and not closed by the user
type(FrameManager),	private,	pointer	::	scene	=>	null()	the scene shown (not owned)
logical,	private		::	scene_added	=	.false.	scene, sky, HUD texts given to the viewer
integer,	private		::	scene_seen	=	-1	the scene's updates at this window's last frame
type(View),	private,	pointer	::	shown	=>	null()	the view whose camera is in the renderer
type(SkySphere),	private,	pointer	::	sky_	=>	null()	the background sky
real(kind=wp),	private		::	switch_duration	=	-1.0_wp	s, for the next view change (< 0: transition_)
real(kind=wp),	private		::	transition_	=	0.0_wp	s, for view changes and resets
type(c_ptr),	private		::	viewer_	=	c_null_ptr	the rendering layer's viewer (null while closed)
type(ViewPointer),	private,	allocatable	::	views(:)			not owned (first n_views used)
integer,	private		::	width_	=	1	logical size (for the views' aspect ratio)
real(kind=wp),	private		::	zoom_speed_	=	1.0_wp	the trackball's zoom per scroll step and drag (1: VSG's)

Type-Bound Procedures

procedure, public :: add_hud_text

private subroutine add_hud_text(self, h)

Show h in the window, on top of the scene (it must stay alive while shown), from the next frame.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
type(HUDText),	intent(in),		target	::	h	the text (not owned)

procedure, public :: add_view

private subroutine add_view(self, v)

Add v to the end of the window's views (it must stay alive while added).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
type(View),	intent(in),		target	::	v	the view (not owned)

procedure, public :: background_color

private pure function background_color(self) result(rgb)

The background color [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp), (3)

procedure, public :: camera_throw

private pure function camera_throw(self)

Whether the camera keeps moving after a released drag (set_camera_throw).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value logical

procedure, public :: capture

private function capture(self, file) result(ok)

Save the last frame as an image (format from the file extension, e.g. .png). Returns false on failure.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
character(len=*),	intent(in)			::	file	image file name (e.g. .png)

Return Value logical

procedure, public :: clear_event_handler

private subroutine clear_event_handler(self)

Give the events to no handler (the built-in keys remain).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self

procedure, public :: clock

private function clock(self) result(c)

The window's simulation clock (e.g. to synchronize it with another window's).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in),		target	::	self

Return Value type(SimulationClock), pointer

procedure, public :: close

private subroutine close(self)

Close the window (waiting for the GPU). The scene is kept, and can be shown again in another window. So are the window's settings (views, HUD texts, sky, handler, time): open again (e.g. on a host's new native window, after Qt destroyed the old one) shows them as before.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self

procedure, public :: current_view

private function current_view(self) result(v)

The view shown (the default view of the scene's root if none were added).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in),		target	::	self

Return Value type(View), pointer

procedure, public :: cursor_ray

private function cursor_ray(self, x, y, origin, direction) result(ok)

The ray from the eye through point (x, y) of the window (-1 to 1 across it, y up: as the event handler's positions), in the root frame, as at the last frame: its origin (the eye; in an orthographic view, on the eye's plane) and its direction (a unit vector). False before the first frame. E.g. where the cursor points on a plane: vkf_pick's ray_plane.

Arguments

Type	Intent		Name
class(WindowProxy),	intent(in)	::	self
real(kind=wp),	intent(in)	::	x	-1 to 1 across the window, y up
real(kind=wp),	intent(in)	::	y	-1 to 1 across the window, y up
real(kind=wp),	intent(out)	::	origin(3)	root frame (direction: a unit vector)
real(kind=wp),	intent(out)	::	direction(3)	root frame (direction: a unit vector)

Return Value logical

procedure, public :: default_keys

private pure function default_keys(self)

Whether the built-in keys are on (set_default_keys).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value logical

procedure, public :: device_info

private function device_info(self) result(info)

The window's Vulkan device and driver (see vkf_diagnostics); '' while it isn't open.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value type(DeviceInfo)

procedure, public :: event_handler

private function event_handler(self) result(handler)

The event handler (null if none).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value class(WindowEventHandler), pointer

procedure, public :: frame

private function frame(self) result(running)

Render one frame: advance the clock, update the frames and draw. Returns false once the window has been closed (or on failure).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self

Return Value logical

procedure, public :: get_camera

private subroutine get_camera(self, eye, center, up, in_root)

The camera of the view shown (from the last frame): eye, center and up in the view frame's coordinates (OpenFrames' trackball getTransformation), or in its root frame's if in_root. Zero before the window's first frame.

Arguments

Type	Intent	Optional		Name
class(WindowProxy),	intent(in)		::	self
real(kind=wp),	intent(out)		::	eye(3)	view frame's coordinates (or root's)
real(kind=wp),	intent(out)		::	center(3)	view frame's coordinates (or root's)
real(kind=wp),	intent(out)		::	up(3)	view frame's coordinates (or root's)
logical,	intent(in),	optional	::	in_root	true: in the root frame's coordinates (default: the view frame's)

procedure, public :: gui => window_gui

private function window_gui(self, font, size) result(g)

The window's GUI panels (vkf_gui), made on first use: with font (a font file name or path, as labels'; default DejaVu Sans) of size window units (default 15), which apply then. Not valid unless open.

Arguments

Type	Intent	Optional		Name
class(WindowProxy),	intent(in)		::	self
character(len=*),	intent(in),	optional	::	font	file name or path (default DejaVu Sans)
real(kind=wp),	intent(in),	optional	::	size	window units (default 15)

Return Value type(Gui)

procedure, public :: in_transition

private pure function in_transition(self)

True while the camera is flying (a transition).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value logical

procedure, public :: is_open

private pure function is_open(self)

Whether the window is open (not closed, by the program or the user).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value logical

procedure, public :: is_recording

private pure function is_recording(self)

Whether the window is recording a video.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value logical

procedure, public :: is_time_paused

private function is_time_paused(self)

Whether the simulation time is paused.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value logical

procedure, public :: key

private subroutine key(self, pressed, symbol, modified_symbol, modifier)

A key press (pressed true) or release, as VSG key symbols and modifiers (ASCII for printable keys; vsg/ui/KeyEvent.h).

Arguments

Type	Intent		Name
class(WindowProxy),	intent(inout)	::	self
logical,	intent(in)	::	pressed	true: pressed; false: released
integer,	intent(in)	::	symbol	the key without modifiers (VSG's keyBase)
integer,	intent(in)	::	modified_symbol	the key with the modifiers (VSG's keyModified, e.g. 'A')
integer,	intent(in)	::	modifier	the modifier keys held (MOD_* bits)

procedure, public :: light_ambient

private pure function light_ambient(self) result(rgb)

The ambient color of the window's light [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp), (3)

procedure, public :: light_diffuse

private pure function light_diffuse(self) result(rgb)

The diffuse color of the window's light [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp), (3)

procedure, public :: light_position

private pure function light_position(self) result(p)

The position of the window's light (see set_light_position).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp), (4)

procedure, public :: light_specular

private pure function light_specular(self) result(rgb)

The specular color of the window's light [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp), (3)

procedure, public :: mouse

private subroutine mouse(self, kind, x, y, mask, button)

A mouse event: kind MOUSE_MOVE, MOUSE_PRESS or MOUSE_RELEASE.

Arguments

Type	Intent		Name
class(WindowProxy),	intent(inout)	::	self
integer,	intent(in)	::	kind	MOUSE_MOVE, MOUSE_PRESS or MOUSE_RELEASE
integer,	intent(in)	::	x	framebuffer pixels from the top left
integer,	intent(in)	::	y	framebuffer pixels from the top left
integer,	intent(in)	::	mask	buttons held (ior: 256 left, 512 middle, 1024 right)
integer,	intent(in)	::	button	button pressed or released (1 left, 2 middle, 3 right)

procedure, public :: next_view

private subroutine next_view(self, duration)

Show the next view (wrapping around); duration as select_view's.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in),	optional		::	duration	s, as select_view's

procedure, public :: num_views

private pure function num_views(self)

Number of views added.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value integer

procedure, public :: open

private function open(self, width, height, title, native_window, pixel_ratio, vsync) result(ok)

Open the window: width x height (logical pixels) titled title, or, with native_window (a host window's native handle) and its pixel_ratio, render into that window. vsync (default true): frames are presented at the display's refresh; false: as soon as they are ready (where the driver allows it), e.g. to measure frame times. Returns false on failure.

Arguments

Type	Intent	Optional		Name
class(WindowProxy),	intent(inout)		::	self
integer,	intent(in)		::	width	window units (logical pixels)
integer,	intent(in)		::	height	window units (logical pixels)
character(len=*),	intent(in),	optional	::	title	default 'vkframes'
integer(kind=c_long_long),	intent(in),	optional	::	native_window	host window's handle (0: own window)
real(kind=wp),	intent(in),	optional	::	pixel_ratio	framebuffer pixels per window unit (default 1)
logical,	intent(in),	optional	::	vsync	default true: at the display's refresh; false: when ready

Return Value logical

procedure, public :: pause_time

private subroutine pause_time(self, paused)

Pause (true) or resume (false) the simulation time.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
logical,	intent(in)			::	paused	true: pause; false: resume

procedure, public :: pick => window_pick

private subroutine window_pick(self, x, y, hits, tolerance, kinds, nearest)

What is under point (x, y) of the window (-1 to 1 across it, y up: as the event handler's positions), nearest first (see the module documentation): none before the first frame. tolerance: how close lines, markers and frames' origins must be, in window units (logical pixels; default 4), beyond half a line's width or a marker's size. kinds: only hits of these kinds (PICK_*; the others aren't tested). nearest: only the nearest hit (cheaper: what is deeper than a hit found is skipped, e.g. to pick on every mouse move). Frames and artists can be left out (set_pickable(.false.)).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in),		target	::	self
real(kind=wp),	intent(in)			::	x	-1 to 1 across the window, y up
real(kind=wp),	intent(in)			::	y	-1 to 1 across the window, y up
type(PickHit),	intent(out),		allocatable	::	hits(:)	what is there, nearest first
real(kind=wp),	intent(in),	optional		::	tolerance	window units (default 4)
integer,	intent(in),	optional		::	kinds(:)	PICK_* (default: all)
logical,	intent(in),	optional		::	nearest	default false

procedure, public :: pixel_ratio

private pure function pixel_ratio(self)

Framebuffer pixels per window unit of a host's window (as given to open or resize; 1 for a window of its own).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp)

procedure, public :: previous_view

private subroutine previous_view(self, duration)

Show the previous view (wrapping around); duration as select_view's.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in),	optional		::	duration	s, as select_view's

procedure, public :: recorded_frames

private pure function recorded_frames(self)

Frames recorded since recording started (the video's length: frames / fps).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value integer(kind=int64)

procedure, public :: remove_all_views

private subroutine remove_all_views(self)

Remove all the window's views (the default view is then used).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self

procedure, public :: remove_hud_text

private subroutine remove_hud_text(self, h)

Stop showing h in the window.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
type(HUDText),	intent(in),		target	::	h	the text to stop showing

procedure, public :: remove_view

private subroutine remove_view(self, v)

Remove all instances of v from the window's views.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
type(View),	intent(in),		target	::	v	the view to remove

procedure, public :: render_stats

private function render_stats(self) result(stats)

The window's frame rate and frame times (see vkf_diagnostics); zeros while it isn't open.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value type(RenderStats)

procedure, public :: resize

private subroutine resize(self, width, height, pixel_ratio)

The host window was resized (framebuffer pixels), and pixel_ratio: its framebuffer pixels per window unit (Qt's devicePixelRatio), if it may have changed (the window moved to a screen of another scale, or the display's scaling changed: sizes in window units, such as line widths, markers and labels, are scaled by it). Once the scene is shown, a frame of the new size is rendered at once (call this from the host's resize event), so that the window isn't shown stretched or blank while it is resized.

Arguments

Type	Intent	Optional		Name
class(WindowProxy),	intent(inout)		::	self
integer,	intent(in)		::	width	framebuffer pixels
integer,	intent(in)		::	height	framebuffer pixels
real(kind=wp),	intent(in),	optional	::	pixel_ratio	framebuffer pixels per window unit

procedure, public :: run

private subroutine run(self, max_frames)

Render frames until the window is closed (or for max_frames frames).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
integer,	intent(in),	optional		::	max_frames	default: until the window is closed

procedure, public :: scene_counts

private function scene_counts(self) result(counts)

The size of the window's scene graph (see vkf_diagnostics): traverses it all, for an occasional update, not every frame. Zeros while it isn't open.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value type(SceneCounts)

procedure, public :: screen_position

private function screen_position(self, p, position) result(visible)

Where point p (root frame) is in the window, as HUD text positions: (x, y) from 0 to 1, left to right and bottom to top (as at the last frame). False if it is behind the eye (or before the first frame). E.g. to keep HUD text next to a moving object, each frame: a callout.

Arguments

Type	Intent		Name
class(WindowProxy),	intent(in)	::	self
real(kind=wp),	intent(in)	::	p(3)	root frame
real(kind=wp),	intent(out)	::	position(2)	(x, y), 0 to 1 from the bottom left

Return Value logical

procedure, public :: scroll

private subroutine scroll(self, dy)

The scroll wheel: dy > 0 away from the user.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	dy	wheel steps (> 0: away from the user; fractions for a trackpad's small steps: Qt's angleDelta / 120)

procedure, public :: select_view

private subroutine select_view(self, i, duration)

Show view i (1 to num_views), flying there over duration s (default: the view transition, set_view_transition; 0: a cut).

Arguments

Type	Intent	Optional		Name
class(WindowProxy),	intent(inout)		::	self
integer,	intent(in)		::	i	1 to num_views
real(kind=wp),	intent(in),	optional	::	duration	s (default: the view transition; 0: a cut)

procedure, public :: set_background_color

private subroutine set_background_color(self, rgb)

The background color [r, g, b] (0 to 1; default black).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	[r, g, b], 0 to 1

procedure, public :: set_camera

private subroutine set_camera(self, eye, center, up, duration, in_root)

Set the camera of the current view: eye, center and up in the view frame's coordinates (OpenFrames' trackball setTransformation), or in its root frame's if in_root (as the frames are now). With duration (s), fly there from the camera shown. Before the view is shown, it is its camera when it is (set_camera).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout),		target	::	self
real(kind=wp),	intent(in)			::	eye(3)	view frame's coordinates (or root's)
real(kind=wp),	intent(in)			::	center(3)	view frame's coordinates (or root's)
real(kind=wp),	intent(in)			::	up(3)	view frame's coordinates (or root's)
real(kind=wp),	intent(in),	optional		::	duration	s (default: at once)
logical,	intent(in),	optional		::	in_root	true: eye, center and up are in the root frame's coordinates

procedure, public :: set_camera_throw

private subroutine set_camera_throw(self, enabled)

Whether the camera keeps moving (turning, zooming, panning) after a drag is released while the mouse moves (default true, VSG's and OSG's throw); false: it stops where it is released.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
logical,	intent(in)			::	enabled	true: keeps moving; false: stops where released

procedure, public :: set_default_keys

private subroutine set_default_keys(self, on)

The built-in keys (default on): v the next view, V the previous one, the space bar resets the view.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
logical,	intent(in)			::	on	true: the built-in keys on

procedure, public :: set_event_handler

private subroutine set_event_handler(self, handler)

Give the window's keyboard and mouse events to handler (not owned: it must stay alive while set), in place of any handler set before.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
class(WindowEventHandler),	intent(in),		target	::	handler	not owned

procedure, public :: set_light_ambient

private subroutine set_light_ambient(self, rgb)

The ambient, diffuse and specular colors ([r, g, b], 0 to 1) of the window's light (OpenFrames' defaults: 0.2 gray, white, none). The window's light is used while no frame of the scene has a light source (set_light_source_enabled).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	[r, g, b], 0 to 1 (default 0.2 gray)

procedure, public :: set_light_diffuse

private subroutine set_light_diffuse(self, rgb)

The diffuse color of the window's light (see set_light_ambient).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	[r, g, b], 0 to 1 (default white)

procedure, public :: set_light_position

private subroutine set_light_position(self, position)

The light's position in eye coordinates (x right, y up, z toward the viewer): [x, y, z, 0] for a directional light from direction (x, y, z), [x, y, z, 1] for a point light (OpenFrames' setLightPosition; default [0, 0, 1, 0], a headlight).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	position(4)	[x, y, z, w], eye coordinates (not all 0)

procedure, public :: set_light_specular

private subroutine set_light_specular(self, rgb)

The specular color of the window's light (see set_light_ambient).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	[r, g, b], 0 to 1 (default black: none)

procedure, public :: set_scene

private subroutine set_scene(self, fm)

Show the scene of fm (which must stay alive while shown). For now, set it before the window's first frame.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
type(FrameManager),	intent(in),		target	::	fm	the scene (not owned; must stay alive while shown)

procedure, public :: set_sky

private subroutine set_sky(self, sky)

Draw sky behind the scene (it must stay alive while shown; it can be shown in several windows), in place of the window's sky so far; at any time (its texture and stars can change too).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
type(SkySphere),	intent(inout),		target	::	sky	the sky (not owned; can be shown in several windows)

procedure, public :: set_time

private subroutine set_time(self, t)

Set the simulation time (limited to the time range).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	t	simulation time

procedure, public :: set_time_range

private subroutine set_time_range(self, t_min, t_max)

Limit the simulation time to [t_min, t_max] (ignored if t_max < t_min).

Arguments

Type	Intent		Name
class(WindowProxy),	intent(inout)	::	self
real(kind=wp),	intent(in)	::	t_min	simulation times
real(kind=wp),	intent(in)	::	t_max	simulation times

procedure, public :: set_time_scale

private subroutine set_time_scale(self, scale)

Simulation seconds per wall-clock second (may be 0 or negative).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	scale	simulation s per wall-clock s (may be 0 or negative)

procedure, public :: set_view_transition

private subroutine set_view_transition(self, seconds)

The time (s) a change of view or a reset flies from one camera to the other (default 0: a cut, as OpenFrames).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	seconds	wall-clock s (0: a cut)

procedure, public :: set_zoom_speed

private subroutine set_zoom_speed(self, speed)

How fast the mouse zooms (default 1, VSG's: 10% per wheel step, and a right drag's rate): e.g. 0.3 for a gentler zoom. Scales scroll steps however they come (a mouse wheel, a trackpad, a host's scroll).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	speed	(> 0; 1: the default)

procedure, public :: sky

private function sky(self) result(s)

The sky drawn behind the scene (null if none).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value type(SkySphere), pointer

procedure, public :: start_recording

private function start_recording(self, file, fps, quality, codec, scale, options, watermark, watermark_width, watermark_opacity, ffmpeg) result(ok)

Start recording the frames drawn to the video file (see the module documentation), fps frames per second (default 30). Encoded by codec (an ffmpeg encoder; default libx264, H.264) at quality (for libx264, libx265 and libvpx-vp9 the CRF: 0 lossless to 51, default 18, visually lossless), scaled by scale (default 1; e.g. 0.5 for half the size of a Retina window's pixels), the size made even. options replaces the encoder options (codec, quality; and the scale, unless there is a watermark), e.g. '-c:v prores_ks -profile:v 3'. watermark: an image (e.g. a logo; PNG, SVG, ... with transparency) drawn over the video's bottom right corner by ffmpeg, watermark_width of the video's width (default 0.2), watermark_opacity opaque (default 0.6). ffmpeg: the program (default: VKFRAMES_FFMPEG, else ffmpeg on the path). Returns false if the window isn't open, is already recording or the watermark doesn't exist; ffmpeg's errors (e.g. an unknown encoder) show when it starts, at the next frame, and end the recording.

Arguments

Type	Intent	Optional		Name
class(WindowProxy),	intent(inout)		::	self
character(len=*),	intent(in)		::	file	the video file (e.g. .mp4, .mov, .webm)
real(kind=wp),	intent(in),	optional	::	fps	frames per second of the video (default 30)
integer,	intent(in),	optional	::	quality	the CRF (default 18; lower is better)
character(len=*),	intent(in),	optional	::	codec	an ffmpeg encoder (default libx264)
real(kind=wp),	intent(in),	optional	::	scale	of the window's pixels (default 1)
character(len=*),	intent(in),	optional	::	options	ffmpeg's encoder options, instead of those above
character(len=*),	intent(in),	optional	::	watermark	an image file drawn at the bottom right
real(kind=wp),	intent(in),	optional	::	watermark_width	its width, of the video's (default 0.2)
real(kind=wp),	intent(in),	optional	::	watermark_opacity	0 to 1 (default 0.6)
character(len=*),	intent(in),	optional	::	ffmpeg	the ffmpeg program

Return Value logical

procedure, public :: stop_recording

private function stop_recording(self, frames) result(ok)

Stop recording: ffmpeg finishes the file. The window's time goes on from where the video was, on the wall clock again. frames: the frames written. Returns false if not recording or if the recording failed (ffmpeg's messages are on the standard error).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self
integer(kind=int64),	intent(out),	optional		::	frames	frames written to the video

Return Value logical

procedure, public :: stop_transition

private subroutine stop_transition(self)

End a flight where the camera is now.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(inout)			::	self

procedure, public :: time

private function time(self)

The simulation time (at the last frame).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp)

procedure, public :: time_range

private subroutine time_range(self, t_min, t_max)

The simulation time range (set_time_range).

Arguments

Type	Intent		Name
class(WindowProxy),	intent(in)	::	self
real(kind=wp),	intent(out)	::	t_min	simulation times
real(kind=wp),	intent(out)	::	t_max	simulation times

procedure, public :: time_scale

private function time_scale(self)

Simulation seconds per wall-clock second.

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp)

procedure, public :: view => window_view

private function window_view(self, i) result(v)

View i (1 to num_views).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self
integer,	intent(in)			::	i	1 to num_views

Return Value type(View), pointer

procedure, public :: view_transition

private pure function view_transition(self)

The time (s) a change of view or a reset flies (set_view_transition).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp)

procedure, public :: viewer => window_viewer

private function window_viewer(self) result(v)

The window's viewer handle in the rendering layer (null until open), for adding low-level nodes (src/vsg/vkf_layer.f90).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value type(c_ptr)

procedure, public :: zoom_speed

private pure function zoom_speed(self)

The zoom speed (set_zoom_speed).

Arguments

Type	Intent	Optional	Attributes		Name
class(WindowProxy),	intent(in)			::	self

Return Value real(kind=wp)

Source Code

    type, public :: WindowProxy
        private
        type(c_ptr) :: viewer_ = c_null_ptr                 !! the rendering layer's viewer (null while closed)
        type(FrameManager), pointer :: scene => null()      !! the scene shown (not owned)
        integer :: scene_seen = -1                          !! the scene's updates at this window's last frame
        type(SimulationClock) :: clock_                     !! the window's simulation clock
        logical :: scene_added = .false.                    !! scene, sky, HUD texts given to the viewer
        real(wp) :: background(3) = [0.0_wp, 0.0_wp, 0.0_wp]  !! background color [r, g, b] (0 to 1)
        logical :: running = .false.                        !! open, and not closed by the user
        integer :: width_ = 1, height_ = 1                  !! logical size (for the views' aspect ratio)
        real(wp) :: pixel_ratio_ = 1.0_wp                   !! framebuffer pixels per window unit (a host's window)
        ! views
        type(ViewPointer), allocatable :: views(:)          !! not owned (first n_views used)
        integer :: n_views = 0, current = 0                 !! number of views; the current one (0: none)
        type(View) :: default_view                          !! used when there are no views
        type(View), pointer :: shown => null()              !! the view whose camera is in the renderer
        ! HUD text
        type(HUDEntry), allocatable :: huds(:)              !! the HUD texts shown (first n_huds used)
        integer :: n_huds = 0                               !! number of HUD texts
        type(SkySphere), pointer :: sky_ => null()          !! the background sky
        ! the window's light (OpenFrames' default: a headlight)
        real(wp) :: light_ambient_(3) = 0.2_wp, light_diffuse_(3) = 1.0_wp, light_specular_(3) = 0.0_wp  !! [r, g, b]
        real(wp) :: light_position_(4) = [0.0_wp, 0.0_wp, 1.0_wp, 0.0_wp]  !! eye coordinates (w 0: directional)
        logical :: light_on = .true.                        !! the window's light enabled (no frame's light source)
        ! keyboard and mouse
        class(WindowEventHandler), pointer :: handler => null()  !! the program's event handler (not owned)
        class(DragHandle), pointer :: hovered_handle => null()   !! the handle under the cursor (not owned)
        class(DragHandle), pointer :: dragged_handle => null()   !! the handle grabbed (not owned)
        logical :: default_keys_ = .true.                   !! the built-in keys on
        logical :: hosted = .false.                         !! in a host's window (its size from [[resize]])
        ! camera transitions
        real(wp) :: transition_ = 0.0_wp                    !! s, for view changes and resets
        real(wp) :: switch_duration = -1.0_wp               !! s, for the next view change (< 0: transition_)
        type(CameraFlight) :: flight                        !! the camera flight (when active)
        real(wp) :: zoom_speed_ = 1.0_wp                    !! the trackball's zoom per scroll step and drag (1: VSG's)
        logical :: camera_throw_ = .true.                   !! the camera keeps moving after a drag released while moving
        ! video recording
        logical :: recording_ = .false.                     !! recording (start_recording)
        real(wp) :: record_fps = 30.0_wp                    !! the video's frames per second
        real(wp) :: record_wall = 0.0_wp                    !! the wall time at the start (s)
        integer(int64) :: record_frames = 0_int64           !! frames drawn while recording
        ! diagnostics (render_stats)
        real(wp) :: rate_start = -1.0_wp                    !! the wall time the frames are counted from (s; -1: none)
        integer :: rate_frames = 0                          !! frames since then
        real(wp) :: fps_ = 0.0_wp                           !! frames per second (the last count's)
        real(wp) :: frame_ms_ = 0.0_wp                      !! milliseconds between frames (the last count's)
        real(wp) :: last_frame_ms = 0.0_wp                  !! the last frame()'s duration (ms)
    contains
        procedure :: open, close, is_open, pixel_ratio
        procedure :: set_scene
        procedure :: frame, run
        procedure :: capture
        ! video recording (see the module documentation)
        procedure :: start_recording, stop_recording, is_recording, recorded_frames
        ! diagnostics (vkf_diagnostics)
        procedure :: render_stats, device_info, scene_counts
        procedure :: set_background_color, background_color
        ! views (OpenFrames' RenderRectangle)
        procedure :: add_view, remove_view, remove_all_views
        procedure :: select_view, next_view, previous_view
        procedure :: current_view, num_views
        ! the camera (OpenFrames' trackball transformation), smooth transitions
        procedure :: get_camera, set_camera
        procedure :: set_view_transition, view_transition, in_transition, stop_transition
        procedure :: set_zoom_speed, zoom_speed, set_camera_throw, camera_throw
        ! picking (see the module documentation), and where points are on the screen
        procedure :: pick => window_pick
        procedure :: screen_position, cursor_ray
        ! GUI panels (vkf_gui)
        procedure :: gui => window_gui
        ! HUD text (OpenFrames' RenderRectangle HUD)
        procedure :: add_hud_text, remove_hud_text
        procedure :: set_sky, sky
        procedure :: set_light_ambient, set_light_diffuse, set_light_specular, set_light_position
        procedure :: light_ambient, light_diffuse, light_specular, light_position
        procedure :: view => window_view
        ! simulation time (OpenFrames' WindowProxy time control)
        procedure :: set_time, time, pause_time, is_time_paused, set_time_scale, time_scale
        procedure :: set_time_range, time_range, clock
        procedure :: viewer => window_viewer
        ! events from a host window
        procedure :: mouse, scroll, key, resize
        ! the program's event handler (OpenFrames' callbacks), built-in keys
        procedure :: set_event_handler, clear_event_handler, event_handler
        procedure :: set_default_keys, default_keys
    end type WindowProxy

WindowProxy Derived Type

Contents

Variables

Type-Bound Procedures

Source Code

type, public :: WindowProxy

Inherits

Components

Type-Bound Procedures

procedure, public :: add_hud_text

private subroutine add_hud_text(self, h)

Arguments

procedure, public :: add_view

private subroutine add_view(self, v)

Arguments

procedure, public :: background_color

private pure function background_color(self) result(rgb)

Arguments

Return Value real(kind=wp), (3)

procedure, public :: camera_throw

private pure function camera_throw(self)

Arguments

Return Value logical

procedure, public :: capture

private function capture(self, file) result(ok)

Arguments

Return Value logical

procedure, public :: clear_event_handler

private subroutine clear_event_handler(self)

Arguments

procedure, public :: clock

private function clock(self) result(c)

Arguments

Return Value type(SimulationClock), pointer

procedure, public :: close

private subroutine close(self)

Arguments

procedure, public :: current_view

private function current_view(self) result(v)

Arguments

Return Value type(View), pointer

procedure, public :: cursor_ray

private function cursor_ray(self, x, y, origin, direction) result(ok)

Arguments

Return Value logical

procedure, public :: default_keys

private pure function default_keys(self)

Arguments

Return Value logical

procedure, public :: device_info

private function device_info(self) result(info)

Arguments

Return Value type(DeviceInfo)

procedure, public :: event_handler

private function event_handler(self) result(handler)

Arguments

Return Value class(WindowEventHandler), pointer

procedure, public :: frame

private function frame(self) result(running)

Arguments

Return Value logical

procedure, public :: get_camera

private subroutine get_camera(self, eye, center, up, in_root)

Arguments

procedure, public :: gui => window_gui

private function window_gui(self, font, size) result(g)

Arguments

Return Value type(Gui)

procedure, public :: in_transition

private pure function in_transition(self)

Arguments

Return Value logical

procedure, public :: is_open

private pure function is_open(self)

Arguments

Return Value logical

procedure, public :: is_recording

private pure function is_recording(self)

Arguments

Return Value logical