vkf_line_segments Module

Custom line segments, as OpenFrames' CustomLineSegments: a frame drawing line segments whose endpoints and colors (one per endpoint, blended along the segment) are set by the program (set_segments), or computed each frame by a callback (set_callback): e.g. lines of sight between spacecraft, or links between ground stations and satellites.

The endpoints are in the frame's own coordinates (the frame can move like any other); position_of(other) gives another frame's origin in them. The callback, an extension of the abstract LineSegmentsCallback (OpenFrames' CustomLineSegments::Callback), is called once per scene update with the simulation time, after the whole tree has been updated (late_update), so the positions of other frames are those for that time whatever their place in the tree; it sets the segments with set_segments. Setting the same segments again uploads nothing.

The segments are drawn by a LineChain of separate segments (vkf_line_chain: thick lines in window units, square caps, dash patterns, points kept to double precision), with a color per point (vkf_line_create_colored). Without colors, the segments take the frame's color (set_color). (OpenFrames' custom line shader, setLineShader, isn't available: it would need GLSL compiled at run time.)


Uses

  • module~~vkf_line_segments~~UsesGraph module~vkf_line_segments vkf_line_segments iso_c_binding iso_c_binding module~vkf_line_segments->iso_c_binding module~vkf_frames vkf_frames module~vkf_line_segments->module~vkf_frames module~vkf_line_chain vkf_line_chain module~vkf_line_segments->module~vkf_line_chain module~vkf_math vkf_math module~vkf_line_segments->module~vkf_math module~vkf_frames->iso_c_binding module~vkf_frames->module~vkf_math module~vkf_follower vkf_follower module~vkf_frames->module~vkf_follower module~vkf_geometry vkf_geometry module~vkf_frames->module~vkf_geometry module~vkf_layer vkf_layer module~vkf_frames->module~vkf_layer module~vkf_pick vkf_pick module~vkf_frames->module~vkf_pick module~vkf_text vkf_text module~vkf_frames->module~vkf_text module~vkf_trajectory vkf_trajectory module~vkf_frames->module~vkf_trajectory module~vkf_line_chain->iso_c_binding module~vkf_line_chain->module~vkf_math module~vkf_line_chain->module~vkf_layer iso_fortran_env iso_fortran_env module~vkf_math->iso_fortran_env module~vkf_follower->module~vkf_math module~vkf_follower->module~vkf_trajectory module~vkf_geometry->iso_c_binding module~vkf_geometry->module~vkf_math module~vkf_geometry->module~vkf_layer module~vkf_layer->iso_c_binding module~vkf_pick->module~vkf_math module~vkf_text->iso_c_binding module~vkf_text->module~vkf_math module~vkf_text->module~vkf_layer module~vkf_files vkf_files module~vkf_text->module~vkf_files module~vkf_trajectory->iso_c_binding module~vkf_trajectory->module~vkf_math module~vkf_trajectory->iso_fortran_env

Used by

  • module~~vkf_line_segments~~UsedByGraph module~vkf_line_segments vkf_line_segments module~vkframes vkframes module~vkframes->module~vkf_line_segments

Interfaces

public interface CustomLineSegments

The CustomLineSegments constructor: CustomLineSegments(...) makes one (see new_custom_line_segments for its arguments).

  • private function new_custom_line_segments(name, color, width) result(s)

    Line segments named name, of color (for segments set without colors; default white) and width (window units; default 1).

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: name

    the frame's name
    real(kind=wp), intent(in), optional :: color(:)

    [r, g, b] or [r, g, b, a] (0 to 1)
    real(kind=wp), intent(in), optional :: width

    line width (window units)

    Return Value type(CustomLineSegments)


Abstract Interfaces

abstract interface

  • private subroutine segments_compute(self, segments, t)

    Set segments' segments for simulation time t (with set_segments).

    Arguments

    Type IntentOptional Attributes Name
    class(LineSegmentsCallback), intent(inout) :: self
    class(CustomLineSegments), intent(inout) :: segments

    the line segments the callback is set on
    real(kind=wp), intent(in) :: t

    simulation time (s)

Derived Types

type, public, extends(ReferenceFrame) ::  CustomLineSegments

Line segments with a color per endpoint (see the module documentation).

Components

Type Visibility Attributes Name Initial
real(kind=wp), private, allocatable :: a(:,:)

(3, n): their endpoints (frame coordinates)
real(kind=wp), private, allocatable :: b(:,:)

(3, n): their endpoints (frame coordinates)
class(LineSegmentsCallback), private, pointer :: callback => null()

computes the segments each frame (not owned)
type(LineChain), private :: chain

draws the segments (separate, colored)
logical, private :: changed = .true.

to write and upload at the next update
real(kind=c_float), private, allocatable :: color_a(:,:)

(4, n), or not allocated: the frame's color
real(kind=c_float), private, allocatable :: color_b(:,:)

(4, n), or not allocated: the frame's color
integer, private :: n = 0

segments
integer, private :: n_drawn = 0

segments written to the chain (drawn)
integer, private :: pattern_ = int(z'FFFF')

16-bit dash pattern (z'FFFF': solid)
integer, private :: pattern_factor = 1

window units per bit of the dash pattern
real(kind=wp), private :: width_ = 1.0_wp

line width (window units)

Constructor

The CustomLineSegments constructor: CustomLineSegments(...) makes one (see new_custom_line_segments for its arguments).

private function new_custom_line_segments (name, color, width)

Line segments named name, of color (for segments set without colors; default white) and width (window units; default 1).

Type-Bound Procedures

procedure, public :: add_child
procedure, public :: attitude
procedure, public :: axes_labels_shown
procedure, public :: axes_shown
procedure, public :: axis_label
procedure, public :: bound => segments_bound
procedure, public :: build_contents => segments_build_contents
procedure, public :: child
procedure, public :: child_index
procedure, public :: clear_callback
procedure, public :: clear_segments
procedure, public :: color
procedure, public :: contents_shown
procedure, public :: detach
procedure, public :: drawn_segment
procedure, public :: follow
procedure, public :: follow_frame
procedure, public :: follower
procedure, public :: frame_info => segments_frame_info
procedure, public :: frame_string
procedure, public :: has_light_source
procedure, public :: is_following
procedure, public :: label_alignment
procedure, public :: label_font
procedure, public :: label_size
procedure, public :: late_update => segments_late_update
procedure, public :: light_ambient
procedure, public :: light_diffuse
procedure, public :: light_source_enabled
procedure, public :: light_specular
procedure, public :: line_width
procedure, public :: local_matrix
procedure, public :: local_matrix_at
procedure, public :: motion_key
procedure, public :: move_x_axis
procedure, public :: move_y_axis
procedure, public :: move_z_axis
procedure, public :: name
procedure, public :: name_label_on_top
procedure, public :: name_label_shown
procedure, public :: node
procedure, public :: num_children
procedure, public :: num_drawn
procedure, public :: num_parents
procedure, public :: num_segments
procedure, public :: parent
procedure, public :: parent_index
procedure, public :: pattern
procedure, public :: pick
procedure, public :: pickable
procedure, public :: position
procedure, public :: position_of
procedure, public :: realize
procedure, public :: remove_child
procedure, public :: reposition_axes
procedure, public :: segment
procedure, public :: set_attitude
procedure, public :: set_callback
procedure, public :: set_color => segments_set_color
procedure, public :: set_label_alignment
procedure, public :: set_label_font
procedure, public :: set_label_size
procedure, public :: set_light_ambient
procedure, public :: set_light_diffuse
procedure, public :: set_light_source_enabled
procedure, public :: set_light_specular
procedure, public :: set_line_width
procedure, public :: set_name
procedure, public :: set_name_label_on_top
procedure, public :: set_pattern
procedure, public :: set_pickable
procedure, public :: set_position
procedure, public :: set_segments
procedure, public :: set_x_label
procedure, public :: set_y_label
procedure, public :: set_z_label
procedure, public :: show_axes
procedure, public :: show_axes_labels
procedure, public :: show_contents
procedure, public :: show_decorations
procedure, public :: show_name_label
procedure, public :: sync
procedure, public :: unfollow
procedure, public :: update
procedure, public :: world_matrix
procedure, public :: world_matrix_at

type, public, abstract ::  LineSegmentsCallback

Computes a CustomLineSegments' segments each frame: extend it with a compute procedure, which calls segments%set_segments (OpenFrames' CustomLineSegments::Callback). The program owns the callback object (it must stay alive while set).

Type-Bound Procedures

procedure(segments_compute), public, deferred :: compute

Functions

private pure function line_width(self)

Line width (window units).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self

Return Value real(kind=wp)

private function new_custom_line_segments(name, color, width) result(s)

Line segments named name, of color (for segments set without colors; default white) and width (window units; default 1).

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: name

the frame's name
real(kind=wp), intent(in), optional :: color(:)

[r, g, b] or [r, g, b, a] (0 to 1)
real(kind=wp), intent(in), optional :: width

line width (window units)

Return Value type(CustomLineSegments)

private pure function num_drawn(self)

Segments drawn now (0 until shown and updated).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self

Return Value integer

private pure function num_segments(self)

Number of segments set.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self

Return Value integer

private function segment_color(self, c, i) result(rgba4)

Color i of c (color_a or color_b), or the frame's color if c is not allocated.

Arguments

Type IntentOptional Attributes Name
type(CustomLineSegments), intent(in) :: self
real(kind=c_float), intent(in), allocatable :: c(:,:)

(4, n): [r, g, b, a]
integer, intent(in) :: i

1 to num_segments

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

private function segments_frame_info(self) result(info)

The kind of frame: 'CustomLineSegments'.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self

Return Value character(len=:), allocatable


Subroutines

private subroutine apply_style(self)

Give the line width and dash pattern to the chain (if built).

Arguments

Type IntentOptional Attributes Name
type(CustomLineSegments), intent(inout) :: self

private subroutine clear_callback(self)

Stop computing the segments with a callback (they stay as last set).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self

private subroutine clear_segments(self)

Remove all segments.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self

private subroutine drawn_segment(self, i, a, b, color_a, color_b)

Segment i as drawn (read back from the GPU buffers, for checks): its endpoints and colors.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self
integer, intent(in) :: i

1 to num_drawn
real(kind=wp), intent(out) :: a(3)

endpoints (frame coordinates)
real(kind=wp), intent(out) :: b(3)

endpoints (frame coordinates)
real(kind=wp), intent(out), optional :: color_a(4)

color at a: [r, g, b, a]
real(kind=wp), intent(out), optional :: color_b(4)

color at b: [r, g, b, a]

private pure subroutine pattern(self, factor, bits)

The dash pattern (see set_pattern).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self
integer, intent(out) :: factor

window units per bit
integer, intent(out) :: bits

16 bits, bit 0 first (65535: solid)

private pure subroutine rgba(c, out)

Colors c (3 or 4 rows) into rgba(4, n) (alpha 1 if not given).

Arguments

Type IntentOptional Attributes Name
real(kind=wp), intent(in) :: c(:,:)

(3 or 4, n): [r, g, b(, a)] (0 to 1)
real(kind=c_float), intent(out) :: out(:,:)

(4, n): [r, g, b, a]

private subroutine segment(self, i, a, b, color_a, color_b)

Segment i: its endpoints, and their colors (rgba).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(in) :: self
integer, intent(in) :: i

1 to num_segments
real(kind=wp), intent(out) :: a(3)

endpoints (frame coordinates)
real(kind=wp), intent(out) :: b(3)

endpoints (frame coordinates)
real(kind=wp), intent(out), optional :: color_a(4)

color at a: [r, g, b, a]
real(kind=wp), intent(out), optional :: color_b(4)

color at b: [r, g, b, a]

private subroutine segments_bound(self, center, radius)

The segments' bounding sphere (frame coordinates).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), 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)

private subroutine segments_build_contents(self, viewer, group)

The chain of separate segments with a color per point, under group.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
type(c_ptr), intent(in) :: viewer

a window's viewer handle (null: headless)
type(c_ptr), intent(in) :: group

the group node to draw under

private recursive subroutine segments_late_update(self, t)

After the tree's update for time t: the callback's segments (all frames at their positions for t), written and uploaded if they changed.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
real(kind=wp), intent(in) :: t

simulation time (s)

private subroutine segments_set_color(self, color)

The frame's color: also that of segments set without colors.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
real(kind=wp), intent(in) :: color(:)

[r, g, b] or [r, g, b, a] (0 to 1)

private subroutine set_callback(self, callback)

Compute the segments each frame with callback (see the module documentation; it must stay alive while set).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
class(LineSegmentsCallback), intent(in), target :: callback

the callback (not owned)

private subroutine set_line_width(self, width)

Line width (window units: logical pixels).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
real(kind=wp), intent(in) :: width

(window units; >= 0)

private subroutine set_pattern(self, factor, pattern)

Dash pattern: OpenGL's line stipple (16 bits, bit 0 first, each factor window units; 65535: solid), as set_pattern.

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
integer, intent(in) :: factor

window units per bit (>= 1)
integer, intent(in) :: pattern

16 bits, bit 0 first (65535: solid)

private subroutine set_segments(self, a, b, color_a, color_b)

The segments: from a(:, i) to b(:, i) (frame coordinates), colored color_a(:, i) at a and color_b(:, i) at b ([r, g, b] or [r, g, b, a] columns; one of them for both ends; neither: the frame's color). Setting the same segments again changes nothing (no upload).

Arguments

Type IntentOptional Attributes Name
class(CustomLineSegments), intent(inout) :: self
real(kind=wp), intent(in) :: a(:,:)

(3, n): first endpoints (frame coordinates)
real(kind=wp), intent(in) :: b(:,:)

(3, n): second endpoints (frame coordinates)
real(kind=wp), intent(in), optional :: color_a(:,:)

(3 or 4, n): colors at a, [r, g, b(, a)] (0 to 1)
real(kind=wp), intent(in), optional :: color_b(:,:)

(3 or 4, n): colors at b, [r, g, b(, a)] (0 to 1)

private subroutine write_segments(self)

The segments into the chain: segment i as points 2i-1 (a) and 2i (b), with their colors; uploaded, and drawn.

Arguments

Type IntentOptional Attributes Name
type(CustomLineSegments), intent(inout) :: self