Sphere – vkframes

type, public, extends(ReferenceFrame) :: Sphere

A sphere or ellipsoid (see the module documentation).

Inherits

Help

Components

Type	Visibility	Attributes		Name		Initial
real(kind=wp),	private		::	ambient_(4)	=	1.0_wp	ambient color [r, g, b, a]
logical,	private		::	auto_lod_	=	.true.	level of detail (default on)
real(kind=wp),	private		::	built_radii(3)	=	1.0_wp	the mesh's semi-axes
real(kind=wp),	private		::	diffuse_(4)	=	1.0_wp	diffuse [r, g, b, a] (times the color if no texture)
real(kind=wp),	private		::	emission_(4)	=	[0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp]	emission color [r, g, b, a]
type(c_ptr),	private		::	image	=	c_null_ptr	the textures, for meshes built later
type(c_ptr),	private		::	lod_mesh(size(lod_segments))	=	c_null_ptr	the level-of-detail meshes (null: not built yet)
type(c_ptr),	private		::	lod_node	=	c_null_ptr	chooses among the meshes, per view
type(c_ptr),	private		::	mesh	=	c_null_ptr	without level of detail
integer,	private		::	n_lat	=	64	without level of detail
integer,	private		::	n_lon	=	128	without level of detail
type(c_ptr),	private		::	night	=	c_null_ptr	the textures, for meshes built later
character(len=:),	private,	allocatable	::	night_texture			night texture file (unallocated or '': none)
real(kind=wp),	private		::	opacity_	=	1.0_wp	1 opaque; below 1 translucent (see set_opacity)
real(kind=wp),	private		::	radius_	=	1.0_wp	radius (scene units; default 1)
real(kind=wp),	private		::	scale_(3)	=	1.0_wp	scale along x, y and z: semi-axes radius * scale
real(kind=wp),	private		::	shininess_	=	0.0_wp	0 to 128 (0: no specular highlight)
logical,	private		::	shown	=	.false.	(meshes built later are compiled)
real(kind=wp),	private		::	specular_(4)	=	[0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp]	specular color [r, g, b, a]
real(kind=wp),	private		::	sphere_attitude_(4)	=	quat_identity	the body's attitude in the frame ([x, y, z, w])
type(c_ptr),	private		::	sphere_node	=	c_null_ptr	transform of the body within the frame
real(kind=wp),	private		::	sphere_position_(3)	=	0.0_wp	the body's center in the frame (scene units)
character(len=:),	private,	allocatable	::	texture			texture file (unallocated or '': none)
logical,	private		::	textured	=	.false.	(the color is not used)
logical,	private		::	translucent	=	.false.	built translucent (opacity below 1 when first shown)
real(kind=wp),	private		::	twilight_	=	0.0_wp	radians below the horizon (0: none)

Constructor

public interface Sphere

The Sphere constructor: Sphere(...) makes one (see new_sphere for its arguments).

private function new_sphere(name, radius, color) result(s)

A sphere named name, of radius radius (default 1) and color color ([r, g, b] or [r, g, b, a]; default white, 90% opaque).

Arguments

Type	Intent	Optional		Name
character(len=*),	intent(in)		::	name	the frame's name
real(kind=wp),	intent(in),	optional	::	radius	scene units (default 1)
real(kind=wp),	intent(in),	optional	::	color(:)	[r, g, b] or [r, g, b, a] (0 to 1)

Return Value type(Sphere)

Type-Bound Procedures

procedure, public :: add_child

private function add_child(self, child) result(ok)

Add child to this frame's children. Returns false (and does nothing) for this frame itself or an ancestor of it; true if it is already a child.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout),		target	::	self
class(ReferenceFrame),	intent(inout),		target	::	child	the frame to add (not owned)

Return Value logical

procedure, public :: attitude

private pure function attitude(self) result(q)

Attitude relative to the parent frame, a quaternion [x, y, z, w].

Arguments

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

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

procedure, public :: auto_lod

private pure function auto_lod(self)

Whether level of detail is on.

Arguments

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

Return Value logical

procedure, public :: axes_labels_shown

private pure function axes_labels_shown(self)

Which axes labels are shown (as axes_shown).

Arguments

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

Return Value integer

procedure, public :: axes_shown

private pure function axes_shown(self)

Which axes vectors are shown (NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined).

Arguments

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

Return Value integer

procedure, public :: axis_label

private function axis_label(self, axis) result(text)

The label text of axis X_AXIS, Y_AXIS or Z_AXIS.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
integer,	intent(in)			::	axis	X_AXIS, Y_AXIS or Z_AXIS (else: '')

Return Value character(len=:), allocatable

procedure, public :: bound => sphere_bound

private subroutine sphere_bound(self, center, radius)

The body's bounding sphere: its center, and its largest semi-axis.

Arguments

Type	Intent		Name
class(Sphere),	intent(in)	::	self
real(kind=wp),	intent(out)	::	center(3)	the bounding sphere, frame coordinates (scene units)
real(kind=wp),	intent(out)	::	radius	the bounding sphere, frame coordinates (scene units)

procedure, public :: build_contents => sphere_build_contents

private subroutine sphere_build_contents(self, viewer, group)

The body: an ellipsoid mesh under the sphere's transform.

Arguments

Type	Intent		Name
class(Sphere),	intent(inout)	::	self
type(c_ptr),	intent(in)	::	viewer	a window's viewer (null: headless)
type(c_ptr),	intent(in)	::	group	the frame's contents group

procedure, public :: child

private function child(self, i) result(c)

Child i (1 to num_children).

Arguments

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

Return Value class(ReferenceFrame), pointer

procedure, public :: child_index

private function child_index(self, frame)

Index of frame among the children, or 0.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
class(ReferenceFrame),	intent(in),		target	::	frame	the frame to find

Return Value integer

procedure, public :: color

private pure function color(self) result(c)

The color of the frame's decorations, [r, g, b, a] (0 to 1).

Arguments

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

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

procedure, public :: contents_shown

private pure function contents_shown(self)

Whether what the frame draws is shown (show_contents).

Arguments

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

Return Value logical

procedure, public :: detach

private subroutine detach(self)

Remove this frame from all its parents and children (before it goes out of scope or is deallocated while in a tree).

Arguments

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

procedure, public :: follow

private subroutine follow(self, traj, data, mode, add, data_frame)

Follow traj (in addition to trajectories already followed, if add is true), with what to follow (data: FOLLOW_POSITION and/or FOLLOW_ATTITUDE; default both) and how (mode: FOLLOW_LOOP, the default, or FOLLOW_LIMIT). traj must stay alive while followed.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
type(Trajectory),	intent(in),		target	::	traj	the trajectory to follow (not owned)
integer,	intent(in),	optional		::	data	FOLLOW_POSITION/FOLLOW_ATTITUDE; FOLLOW_LOOP/FOLLOW_LIMIT
integer,	intent(in),	optional		::	mode	FOLLOW_POSITION/FOLLOW_ATTITUDE; FOLLOW_LOOP/FOLLOW_LIMIT
logical,	intent(in),	optional		::	add	(true: in addition to those followed (default false))
class(ReferenceFrame),	intent(in),	optional,	target	::	data_frame	the frame the data are in (default: the parent)

procedure, public :: follow_frame

private function follow_frame(self) result(f)

The frame the followed data are in (follow's data_frame; null: the parent).

Arguments

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

Return Value class(ReferenceFrame), pointer

procedure, public :: follower

private function follower(self) result(f)

The frame's trajectory follower, for finer control (data sources, time offset, ...).

Arguments

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

Return Value type(TrajectoryFollower), pointer

procedure, public :: frame_info => sphere_frame_info

private function sphere_frame_info(self) result(info)

What kind of frame this is: 'Sphere'.

Arguments

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

Return Value character(len=:), allocatable

procedure, public :: frame_string

private recursive function frame_string(self, prefix) result(str)

The tree below this frame, one line per frame ("name (info)"), in OpenFrames' createFrameString format: children are prefixed "|-->".

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
character(len=*),	intent(in),	optional		::	prefix	before this frame's line (default ' ')

Return Value character(len=:), allocatable

procedure, public :: has_light_source

private recursive function has_light_source(self) result(has)

Whether this frame or one of its descendants has a light source enabled.

Arguments

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

Return Value logical

procedure, public :: is_following

private pure function is_following(self)

Whether the frame follows trajectories (at least one, since follow).

Arguments

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

Return Value logical

procedure, public :: label_alignment

private pure function label_alignment(self)

The labels' alignment (ALIGN_*).

Arguments

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

Return Value integer

procedure, public :: label_font

private function label_font(self) result(font)

The labels' font as set ('' for the renderer's default).

Arguments

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

Return Value character(len=:), allocatable

procedure, public :: label_size

private pure function label_size(self)

The labels' size in pixels.

Arguments

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

Return Value integer

procedure, public :: late_update

private recursive subroutine late_update(self, t)

After the whole tree's update for time t (all frames at their positions for t): for contents that depend on other frames' positions, e.g. CustomLineSegments between spacecraft. Here, only the descendants'.

Arguments

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

procedure, public :: light_ambient

private pure function light_ambient(self) result(rgb)

The light source's ambient color [r, g, b].

Arguments

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

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

procedure, public :: light_diffuse

private pure function light_diffuse(self) result(rgb)

The light source's diffuse color [r, g, b].

Arguments

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

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

procedure, public :: light_source_enabled

private pure function light_source_enabled(self)

Whether this frame carries a light source.

Arguments

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

Return Value logical

procedure, public :: light_specular

private pure function light_specular(self) result(rgb)

The light source's specular color [r, g, b].

Arguments

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

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

procedure, public :: local_matrix

private pure function local_matrix(self) result(m)

The transform from this frame to its parent (4x4).

Arguments

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

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

procedure, public :: local_matrix_at

private recursive function local_matrix_at(self, t) result(m)

The transform from this frame to its parent at simulation time t: its fixed position and attitude, with what it follows at time t (the followed trajectories' state then, in the parent's coordinates). The same as local_matrix after update at time t, for any t, without changing anything.

Arguments

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

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

procedure, public :: material

private pure subroutine material(self, ambient, diffuse, specular, emission, shininess)

The material (each optional): ambient, diffuse, specular and emission colors and shininess.

Arguments

Type	Intent	Optional		Name
class(Sphere),	intent(in)		::	self
real(kind=wp),	intent(out),	optional	::	ambient(4)	[r, g, b, a]
real(kind=wp),	intent(out),	optional	::	diffuse(4)	[r, g, b, a]
real(kind=wp),	intent(out),	optional	::	specular(4)	[r, g, b, a]
real(kind=wp),	intent(out),	optional	::	emission(4)	[r, g, b, a]
real(kind=wp),	intent(out),	optional	::	shininess	0 to 128

procedure, public :: motion_key

private recursive subroutine motion_key(self, stamp, data)

What the frame's motion depends on, for drawings that depend on it to know when to redraw: stamp, the latest change of the motion of it and its ancestors (through first parents), and of the frames their followed data are in (poses set, parents changed, what is followed and how); and data, the followed trajectories' revisions summed. Either changes when the frame's motion over time changes.

Arguments

Type	Intent		Name
class(ReferenceFrame),	intent(in)	::	self
integer,	intent(out)	::	stamp	the latest change; the followed data's revisions
integer,	intent(out)	::	data	the latest change; the followed data's revisions

procedure, public :: move_x_axis

private subroutine move_x_axis(self, base, length, head_ratio, body_radius, head_radius)

Place the x axis vector: from base, length long, with a head of head_ratio of the length (default 0.3) and body and head radii (default 0.05 and 0.1 of the length); its label is at the tip, 0.4 of the length tall (at most label_size pixels). As OpenFrames' moveXAxis. Set before the frame is first shown.

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

procedure, public :: move_y_axis

private subroutine move_y_axis(self, base, length, head_ratio, body_radius, head_radius)

Place the y axis vector (as move_x_axis; OpenFrames' moveYAxis).

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

procedure, public :: move_z_axis

private subroutine move_z_axis(self, base, length, head_ratio, body_radius, head_radius)

Place the z axis vector (as move_x_axis; OpenFrames' moveZAxis).

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

procedure, public :: name

private function name(self) result(n)

The frame's name ('' if none).

Arguments

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

Return Value character(len=:), allocatable

procedure, public :: name_label_on_top

private pure function name_label_on_top(self)

Whether the name label is drawn on top of the scene (set_name_label_on_top).

Arguments

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

Return Value logical

procedure, public :: name_label_shown

private pure function name_label_shown(self)

Whether the name label is shown.

Arguments

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

Return Value logical

procedure, public :: night_texture_map

private function night_texture_map(self) result(file)

The night texture file ('' for none).

Arguments

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

Return Value character(len=:), allocatable

procedure, public :: node

private function node(self) result(n)

The frame's transform node (null until realized).

Arguments

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

Return Value type(c_ptr)

procedure, public :: num_children

private pure function num_children(self)

Number of children.

Arguments

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

Return Value integer

procedure, public :: num_lod_meshes

private function num_lod_meshes(self) result(n)

Number of level-of-detail meshes built so far (0 without level of detail).

Arguments

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

Return Value integer

procedure, public :: num_parents

private pure function num_parents(self)

Number of parents.

Arguments

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

Return Value integer

procedure, public :: opacity

private pure function opacity(self)

The body's opacity (set_opacity).

Arguments

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

Return Value real(kind=wp)

procedure, public :: parent

private function parent(self, i) result(p)

Parent i (1 to num_parents).

Arguments

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

Return Value class(ReferenceFrame), pointer

procedure, public :: parent_index

private function parent_index(self, frame)

Index of frame among the parents, or 0.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
class(ReferenceFrame),	intent(in),		target	::	frame	the frame to find

Return Value integer

procedure, public :: pick => sphere_pick

private subroutine sphere_pick(self, cam, to_root, hits, n)

Picked on the ellipsoid (exact), with the geodetic latitude and longitude of the point hit (in the body's axes: sphere_attitude); else the frame's origin.

Arguments

Type	Intent	Attributes		Name
class(Sphere),	intent(in),	target	::	self
type(PickCamera),	intent(in)		::	cam	the camera and cursor of the pick
real(kind=wp),	intent(in)		::	to_root(4,4)	the frame's transform to the root frame
type(PickHit),	intent(inout),	allocatable	::	hits(:)	hits so far, in hits(1:n); added to
integer,	intent(inout)		::	n	number of hits

procedure, public :: pickable

private pure function pickable(self)

Whether pick tests what this frame draws (set_pickable).

Arguments

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

Return Value logical

procedure, public :: position

private pure function position(self) result(p)

Position relative to the parent frame.

Arguments

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

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

procedure, public :: position_of

private function position_of(self, other) result(p)

The origin of other (a frame of the same tree) in this frame's coordinates, from both frames' transforms to the root (through their first parents).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self	(other: a frame of the same tree)
class(ReferenceFrame),	intent(in)			::	other	(other: a frame of the same tree)

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

procedure, public :: radii

private pure function radii(self) result(r)

The semi-axes: radius * sphere_scale.

Arguments

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

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

procedure, public :: radius

private pure function radius(self)

The sphere's radius (scene units).

Arguments

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

Return Value real(kind=wp)

procedure, public :: realize

private recursive subroutine realize(self, viewer)

Create the render nodes of this frame and its descendants (once; for viewer, a window's viewer handle, which some contents need while they are built (not kept); null: headless).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
type(c_ptr),	intent(in)			::	viewer	a window's viewer handle (null: headless)

procedure, public :: remove_child

private function remove_child(self, child) result(ok)

Remove child from this frame's children. Returns false if it is not one.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout),		target	::	self
class(ReferenceFrame),	intent(inout),		target	::	child	the child to remove

Return Value logical

procedure, public :: reposition_axes

private subroutine reposition_axes(self)

Place the axes for what the frame draws, when it is first shown (unless move_*_axis was called): at its bound's surface, half the bound's radius long (as OpenFrames' Sphere and Model do); at the origin, 1 long, for a frame that draws nothing.

Arguments

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

procedure, public :: set_attitude

private subroutine set_attitude(self, q)

Attitude relative to the parent frame, a quaternion [x, y, z, w] (normalized here; overridden by a followed trajectory).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	q(4)	attitude quaternion [x, y, z, w] (normalized here)

procedure, public :: set_auto_lod

private subroutine set_auto_lod(self, lod)

Level of detail (default on; see the module documentation): meshes of several resolutions, the one drawn chosen per view. Off: one mesh of set_resolution's segments. Set it before a window shows the sphere.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
logical,	intent(in)			::	lod	true: level of detail; false: one mesh

procedure, public :: set_color => sphere_set_color

private subroutine sphere_set_color(self, color)

The body's color (used without a texture); [r, g, b] or [r, g, b, a].

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	color(:)	[r, g, b] or [r, g, b, a] (0 to 1)

procedure, public :: set_label_alignment

private subroutine set_label_alignment(self, alignment)

The alignment of the labels relative to their positions (ALIGN_*; default ALIGN_LEFT_BASE_LINE).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	alignment	ALIGN_* (default ALIGN_LEFT_BASE_LINE)

procedure, public :: set_label_font

private subroutine set_label_font(self, font)

The font of the labels: a font file name (found on the data search path) or a full path; default: the renderer's default font.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	font	a font file name (on the data search path) or a full path

procedure, public :: set_label_size

private subroutine set_label_size(self, size)

The size of the labels in pixels (default 20): the name label's size, and the maximum size of the axes labels (which shrink with distance).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	size	pixels (default 20)

procedure, public :: set_light_ambient

private subroutine set_light_ambient(self, rgb)

The light source's ambient, diffuse and specular colors ([r, g, b], 0 to 1; defaults 0.05, 0.8 and 0.05 gray).

Arguments

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

procedure, public :: set_light_diffuse

private subroutine set_light_diffuse(self, rgb)

The light source's diffuse color (see set_light_ambient).

Arguments

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

procedure, public :: set_light_source_enabled

private subroutine set_light_source_enabled(self, enable)

Whether this frame carries a light source: a point light at its origin (e.g. the Sun), not dimmed with distance (default false; OpenFrames' setLightSourceEnabled). While any frame of a window's scene has one, the window's own light (WindowProxy%set_light_*) is off.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	enable	(true: a point light at the frame's origin)

procedure, public :: set_light_specular

private subroutine set_light_specular(self, rgb)

The light source's specular color (see set_light_ambient).

Arguments

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

procedure, public :: set_material

private subroutine set_material(self, ambient, diffuse, specular, emission, shininess)

The material (OpenFrames' setMaterial; each optional): ambient, diffuse, specular and emission colors ([r, g, b] or [r, g, b, a], 0 to 1) and shininess (0 to 128: the specular highlight's sharpness; 0 for none). The ambient and diffuse colors scale the body's color or texture (VSG's Phong); the specular color is reflected from the lights' specular parts. Defaults: ambient and diffuse white, no specular reflection or emission.

Arguments

Type	Intent	Optional		Name
class(Sphere),	intent(inout)		::	self
real(kind=wp),	intent(in),	optional	::	ambient(:)	[r, g, b(, a)], 0 to 1
real(kind=wp),	intent(in),	optional	::	diffuse(:)	[r, g, b(, a)], 0 to 1
real(kind=wp),	intent(in),	optional	::	specular(:)	[r, g, b(, a)], 0 to 1
real(kind=wp),	intent(in),	optional	::	emission(:)	[r, g, b(, a)], 0 to 1
real(kind=wp),	intent(in),	optional	::	shininess	0 to 128 (< 0: 0)

procedure, public :: set_name

private subroutine set_name(self, name)

The frame's name, shown by its name label (also once shown: e.g. a readout that follows the frame).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	name	the name (shown by the name label)

procedure, public :: set_name_label_on_top

private subroutine set_name_label_on_top(self, on_top)

Draw the name label on top of the scene (true: not hidden by bodies in front of it, as HUD text; e.g. a readout) or depth-tested (false, the default, as OpenFrames').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	on_top	(true: drawn on top of the scene; false: depth-tested)

procedure, public :: set_night_texture_map

private subroutine set_night_texture_map(self, file)

The texture for the side away from the light (e.g. city lights; an equirectangular image file as the texture, '' for none), shown where the diffuse light is weak.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
character(len=*),	intent(in)			::	file	found with find_data_file; '' for none

procedure, public :: set_opacity

private subroutine set_opacity(self, opacity)

The body's opacity, 0 (invisible) to 1 (opaque, the default): below 1 it is drawn translucent (see the module documentation). Set below 1 before a window first shows it to make it translucent; then the opacity can change at any time (a translucent body stays translucent, an opaque one opaque).

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	opacity	0 to 1

procedure, public :: set_pickable

private subroutine set_pickable(self, pickable)

Whether pick tests what this frame draws (default true; e.g. false for an overlay such as a selection marker). Its children are picked or not by their own setting.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	pickable	(true: tested by pick)

procedure, public :: set_position

private subroutine set_position(self, position)

Position relative to the parent frame (overridden by a followed trajectory).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	position(3)	parent frame's coordinates

procedure, public :: set_radius

private subroutine set_radius(self, radius)

The sphere's radius (scene units, > 0; default 1); can change at any time.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	radius	scene units (<= 0: ignored)

procedure, public :: set_resolution

private subroutine set_resolution(self, n_lon, n_lat)

The mesh resolution without level of detail: segments in longitude and latitude (default 128 x 64).

Arguments

Type	Intent		Name
class(Sphere),	intent(inout)	::	self
integer,	intent(in)	::	n_lon	segments in longitude (at least 3)
integer,	intent(in)	::	n_lat	segments in latitude (at least 2)

procedure, public :: set_sphere_attitude

private subroutine set_sphere_attitude(self, q)

Attitude of the body in its frame (quaternion [x, y, z, w]), e.g. to orient its texture.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	q(4)	quaternion [x, y, z, w] (normalized here)

procedure, public :: set_sphere_position

private subroutine set_sphere_position(self, position)

Position of the body's center in its frame.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	position(3)	scene units

procedure, public :: set_sphere_scale

private subroutine set_sphere_scale(self, scale)

Scale the sphere along its x, y and z axes (all > 0), making an ellipsoid with semi-axes radius * scale.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	scale(3)	along x, y and z (all > 0, else ignored)

procedure, public :: set_texture_map

private subroutine set_texture_map(self, file)

The texture: an equirectangular image file ('' for none).

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
character(len=*),	intent(in)			::	file	found with find_data_file; '' for none

procedure, public :: set_twilight

private subroutine set_twilight(self, angle)

The twilight: the diffuse light extended past the terminator to where the light is angle (radians, 0 to 1.5) below the horizon, fading out smoothly (where it meets the light on the day side: the same brightness and slope, so no line shows), and the night texture fading in across it. 0 (the default): none, the light ends at the terminator (an airless body). Not in OpenFrames. Can change at any time.

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	angle	radians below the horizon (clamped to 0 to 1.5)

procedure, public :: set_x_label

private subroutine set_x_label(self, text)

The text of the x-axis label (default 'X').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	text	the x-axis label (default 'X')

procedure, public :: set_y_label

private subroutine set_y_label(self, text)

The text of the y-axis label (default 'Y').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	text	the y-axis label (default 'Y')

procedure, public :: set_z_label

private subroutine set_z_label(self, text)

The text of the z-axis label (default 'Z').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	text	the z-axis label (default 'Z')

procedure, public :: show_axes

private subroutine show_axes(self, axes)

Which axes vectors to show: NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined with ior.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	axes	NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined with ior

procedure, public :: show_axes_labels

private subroutine show_axes_labels(self, labels)

Which axes labels to show (as show_axes).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	labels	NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined with ior

procedure, public :: show_contents

private subroutine show_contents(self, show)

Show or hide what the frame draws (its sphere, model, ...), but not its axes, labels or children.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	show	(true: shown)

procedure, public :: show_decorations

private subroutine show_decorations(self, show)

Show (true) or hide all the frame's decorations at once: its axes, their labels and its name label (show_axes, show_axes_labels, show_name_label).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	show	true: all axes, axes labels and the name label

procedure, public :: show_name_label

private subroutine show_name_label(self, show)

Show or hide the name label (at the frame's origin; default shown).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	show	(true: shown)

procedure, public :: sphere_attitude

private pure function sphere_attitude(self) result(q)

Attitude of the body in its frame (quaternion [x, y, z, w]).

Arguments

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

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

procedure, public :: sphere_position

private pure function sphere_position(self) result(p)

Position of the body's center in its frame (scene units).

Arguments

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

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

procedure, public :: sphere_scale

private pure function sphere_scale(self) result(s)

The scale along the sphere's x, y and z axes.

Arguments

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

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

procedure, public :: sync

private recursive subroutine sync(self)

Copy the positions and attitudes of this frame and its descendants to their transform nodes (only those that changed since the last sync).

Arguments

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

procedure, public :: texture_map

private function texture_map(self) result(file)

The texture file ('' for none).

Arguments

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

Return Value character(len=:), allocatable

procedure, public :: twilight

private pure function twilight(self)

The twilight angle (radians below the horizon; 0: none).

Arguments

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

Return Value real(kind=wp)

procedure, public :: unfollow

private subroutine unfollow(self)

Stop following trajectories (the frame keeps its last position and attitude).

Arguments

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

procedure, public :: update => sphere_update

private recursive subroutine sphere_update(self, t)

Update the frame (followed trajectories, children) and, with level of detail, build the mesh the views have wanted if it isn't built yet (the coarsest with as many segments as wanted, or the finest).

Arguments

Type	Intent	Optional	Attributes		Name
class(Sphere),	intent(inout),		target	::	self
real(kind=wp),	intent(in)			::	t	the scene time

procedure, public :: world_matrix

private recursive function world_matrix(self) result(m)

The transform from this frame to the root of its tree, through the first parent at each level.

Arguments

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

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

procedure, public :: world_matrix_at

private recursive function world_matrix_at(self, t) result(m)

The transform from this frame to the root of its tree at simulation time t (through the first parent at each level): each frame's local_matrix_at time t. The same as world_matrix after the tree's update at time t, for any t, without changing anything.

Arguments

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

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

Source Code

    type, extends(ReferenceFrame), public :: Sphere
        private
        real(wp) :: radius_ = 1.0_wp                          !! radius (scene units; default 1)
        real(wp) :: scale_(3) = 1.0_wp                        !! scale along x, y and z: semi-axes radius * scale
        real(wp) :: sphere_position_(3) = 0.0_wp              !! the body's center in the frame (scene units)
        real(wp) :: sphere_attitude_(4) = quat_identity       !! the body's attitude in the frame ([x, y, z, w])
        real(wp) :: built_radii(3) = 1.0_wp                   !! the mesh's semi-axes
        logical :: textured = .false.                         !! (the color is not used)
        character(len=:), allocatable :: texture              !! texture file (unallocated or '': none)
        character(len=:), allocatable :: night_texture        !! night texture file (unallocated or '': none)
        logical :: auto_lod_ = .true.                         !! level of detail (default on)
        integer :: n_lon = 128, n_lat = 64                    !! without level of detail
        ! material (VSG's Phong; OpenGL's default: no specular reflection)
        real(wp) :: ambient_(4) = 1.0_wp                      !! ambient color [r, g, b, a]
        real(wp) :: diffuse_(4) = 1.0_wp                      !! diffuse [r, g, b, a] (times the color if no texture)
        real(wp) :: specular_(4) = [0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp]  !! specular color [r, g, b, a]
        real(wp) :: emission_(4) = [0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp]  !! emission color [r, g, b, a]
        real(wp) :: shininess_ = 0.0_wp                       !! 0 to 128 (0: no specular highlight)
        real(wp) :: twilight_ = 0.0_wp                        !! radians below the horizon (0: none)
        real(wp) :: opacity_ = 1.0_wp                         !! 1 opaque; below 1 translucent (see set_opacity)
        logical :: translucent = .false.                      !! built translucent (opacity below 1 when first shown)
        type(c_ptr) :: sphere_node = c_null_ptr              !! transform of the body within the frame
        type(c_ptr) :: mesh = c_null_ptr                     !! without level of detail
        ! level of detail
        type(c_ptr) :: lod_node = c_null_ptr                 !! chooses among the meshes, per view
        type(c_ptr) :: lod_mesh(size(lod_segments)) = c_null_ptr  !! the level-of-detail meshes (null: not built yet)
        type(c_ptr) :: image = c_null_ptr, night = c_null_ptr   !! the textures, for meshes built later
        logical :: shown = .false.                            !! (meshes built later are compiled)
    contains
        procedure :: set_radius, radius
        procedure :: set_color => sphere_set_color
        procedure :: set_sphere_scale, sphere_scale, radii
        procedure :: set_sphere_position, sphere_position
        procedure :: set_sphere_attitude, sphere_attitude
        procedure :: set_texture_map, texture_map
        procedure :: set_night_texture_map, night_texture_map
        procedure :: set_auto_lod, auto_lod
        procedure :: set_material, material
        procedure :: set_twilight, twilight
        procedure :: set_opacity, opacity
        procedure :: set_resolution
        procedure :: frame_info => sphere_frame_info
        procedure :: bound => sphere_bound
        procedure :: pick => sphere_pick
        procedure :: build_contents => sphere_build_contents
        procedure :: update => sphere_update
        procedure :: num_lod_meshes
    end type Sphere

Sphere Derived Type

Contents

Variables

Constructor

Type-Bound Procedures

Source Code

type, public, extends(ReferenceFrame) :: Sphere

Inherits

Components

Constructor

public interface Sphere

private function new_sphere(name, radius, color) result(s)

Arguments

Return Value type(Sphere)

Type-Bound Procedures

procedure, public :: add_child

private function add_child(self, child) result(ok)

Arguments

Return Value logical

procedure, public :: attitude

private pure function attitude(self) result(q)

Arguments

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

procedure, public :: auto_lod

private pure function auto_lod(self)

Arguments

Return Value logical

procedure, public :: axes_labels_shown

private pure function axes_labels_shown(self)

Arguments

Return Value integer

procedure, public :: axes_shown

private pure function axes_shown(self)

Arguments

Return Value integer

procedure, public :: axis_label

private function axis_label(self, axis) result(text)

Arguments

Return Value character(len=:), allocatable

procedure, public :: bound => sphere_bound

private subroutine sphere_bound(self, center, radius)

Arguments

procedure, public :: build_contents => sphere_build_contents

private subroutine sphere_build_contents(self, viewer, group)

Arguments

procedure, public :: child

private function child(self, i) result(c)

Arguments

Return Value class(ReferenceFrame), pointer

procedure, public :: child_index

private function child_index(self, frame)

Arguments

Return Value integer

procedure, public :: color

private pure function color(self) result(c)

Arguments

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

procedure, public :: contents_shown

private pure function contents_shown(self)

Arguments

Return Value logical

procedure, public :: detach

private subroutine detach(self)

Arguments

procedure, public :: follow

private subroutine follow(self, traj, data, mode, add, data_frame)

Arguments

procedure, public :: follow_frame

private function follow_frame(self) result(f)

Arguments

Return Value class(ReferenceFrame), pointer

procedure, public :: follower

private function follower(self) result(f)

Arguments

Return Value type(TrajectoryFollower), pointer

procedure, public :: frame_info => sphere_frame_info

private function sphere_frame_info(self) result(info)

Arguments

Return Value character(len=:), allocatable

procedure, public :: frame_string