english
version "1.0"
identify "@(#)layout.sts 1.5 94/11/05 Copyright (c) 1991 -- Wayne C. Gramlich"

module layout

#: This module provides some procedures for drawing model railroad
#, layouts.

define track				#: A track head object
    record
	angle unsigned			#: Current track angle [0-359]
	grade float			#: Current track grade
	layout layout			#: Parent {layout} object
	tunnel logical			#: {true} => track is in tunnel
	x float				#: Current X Coordinate
	y float				#: Current Y coordinate
	z float				#: Current height
    generate allocate, erase, print

define layout
    record
	cosine vector[float]
	count_adjustable unsigned
	count_bumper_concrete unsigned
	count_bumper_wood unsigned
	count_converter unsigned
	count_crossing_15_left unsigned
	count_crossing_15_right unsigned
	count_crossing_90 unsigned
	count_crossover unsigned
	count_curved_249_45 unsigned
	count_curved_282_45 unsigned
	count_curved_282_15 unsigned
	count_curved_315_45 unsigned
	count_curved_315_15 unsigned
	count_curved_348_45 unsigned
	count_curved_348_30 unsigned
	count_curved_381_30 unsigned
	count_curved_481_15 unsigned
	count_curved_718_15 unsigned
	count_feeder unsigned
	count_rerailer unsigned
	count_straight_29 unsigned
	count_straight_45_5 unsigned
	count_straight_62 unsigned
	count_straight_64 unsigned
	count_straight_124 unsigned
	count_straight_186 unsigned
	count_straight_248 unsigned	
	count_turnout_6_left unsigned
	count_turnout_6_right unsigned
	count_uncoupler unsigned
	error_stream out_stream
	fifty float
	gc xlib_gc
	half float
	half_width float
	one float
	parts_stream out_stream
	pi float
	shift unsigned
	sine vector[float]
	surface surface
	track_offset float
	track_scale float
	top_view logical
	window xlib_window
	zero float
    generate allocate, erase, print



procedure adjustable@track
    takes
	track1 track
	track2 track
    returns_nothing

    #: This procedure will connect {track1} to {track2} using {layout}.

    # FIXME: Need code to deal with grades!!!



procedure bumper_concrete@track
    takes
	track track
    returns_nothing

    #: This procedure will attach a concrete bumper to {track}.


procedure bumper_wood@track
    takes
	track track
    returns_nothing

    #: This procedure will attach a wood bumper to {track}.


procedure close@layout
    takes
	layout layout
    returns_nothing


procedure converter@track
    takes
	track track
    returns track

    #: This procedure will draw a 64 millimeter converter track to
    #, {layout} starting from {track}.  The track at the end is returned.


procedure create@layout
    takes
	window xlib_window
	gc xlib_gc
	width unsigned
	height unsigned
	surface surface
	top_view logical
	parts_stream out_stream
	error_stream out_stream
	shift unsigned
    returns layout

    #: This procedure will create and return a {layout} object.


procedure crossing@track
    takes
	track track
	length1 unsigned
	cross_angle unsigned
	length2 unsigned
    returns track, track, track

    #: This procedure draw a double track crossover starting at {track}.
    #, The {length1} is the length of the straight portion of the
    #, crossing.  {cross_angle} is the angle of the crossing track; the
    #, currently manufactured Kato crossings are at 15, 90, and -15
    #, degrees.  -15 degrees is represented by 360 - 15 = 345.  {length2}
    #, is the length of the crossing track.


procedure crossing_15_left@track
    takes
	track track
    returns track, track, track

    #: This procedure will output a 90 degree crossing and returns
    #, the three end point tracks.


procedure crossing_15_right@track
    takes
	track track
    returns track, track, track

    #: This procedure will output a 90 degree crossing and returns
    #, the three end point tracks.


procedure crossing_90@track
    takes
	track track
    returns track, track, track

    #: This procedure will output a 90 degree crossing and returns
    #, the three end point tracks.


procedure crossover@track
    takes
	track track
	upper logical
    returns track, track, track

    #: This procedure will output a Kato crossover unit and returns
    #, the three end point tracks.


procedure curved@track
    takes
	track track
	radius unsigned
	angle_subtended unsigned
	clockwise logical
    returns track

    #: This procedure will draw a curved layout starting at {track}
    #, with a radius of {radus} and an angle subtended of {angle_subtended}.
    #, If {clockwise} is true the curve is in a clockwise direction;
    #, otherwise, it will be in a counter-clockwise direction.


procedure curved_249_45@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 249
    #, millimeters for 45 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_282_45@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 282
    #, millimeters for 45 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_282_15@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 282
    #, millimeters for 15 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_315_45@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 315
    #, millimeters for 45 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_315_15@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 315
    #, millimeters for 15 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_348_45@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 348
    #, millimeters for 45 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_348_30@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 348
    #, millimeters for 30 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_381_30@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 381
    #, millimeters for 30 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_481_15@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 481
    #, millimeters for 15 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure curved_718_15@track
    takes
	track track
	clockwise logical
    returns track

    #: This procedure will draw a curved track with a radius of 718
    #, millimeters for 15 degrees.  If {clockwise} is true the curve
    #, is drawn in a clockwise direction; otherwise it will be in a
    #, counter-clockwise direction.  The end track of the track
    #, is returned.


procedure feeder@track
    takes
	track track
    returns track

    #: This procedure will attach a feeder to {track}.
    #, The end track of the track is returned.


procedure grade@track
    takes
	track track
	new_grade float
    returns track

    #: This procedure will return a copy of {track} using {layout}
    #: whose grade is set to {new_grade}.


procedure invert@track
    takes
	track track
    returns track

    #: This procedure will create and return a track that is pointing 180
    #, in exactly the opposite direction from {track}.


procedure line@track
    takes
	track track
	x1 float
	y1 float
	z1 float
	x2 float
	y2 float
	z2 float
    returns_nothing

    #: This procedure will draw a line from ({x1}, {y1}, {z1}) to
    #, ({x2}, {y2}, {z2}) using {layout}.  The x and y coordinates
    #, are rounded to the nearest coordinate.


procedure track@layout
    takes
	layout layout
	angle unsigned
	x unsigned
	y unsigned
    returns track


procedure part_out@layout
    takes
	layout layout
	count unsigned
	description string
    returns_nothing

    #: This procedure will print {description} to {layout}'s parts stream
    #, if {count} is non-zero.


procedure rerailer@track
    takes
	track track
    returns track

    #: This procedure will attach a rerailer to {track}.
    #, The end track is returned.


procedure show@track
    takes
	track track
	prefix string
	trailer string	
	out_stream out_stream
    returns_nothing

    #: This procedure will output the (x, y, z) coordinate of {track}
    #, to {out_stream}.  It will be preceeded by {prefix} and trailed
    #, {trailer}.


procedure straight@track
    takes
	track track
	length float
    returns track

    #: This procedure will draw a track of {length} millimeters
    #, to {layout} starting from {track}.  The track at the end returned.


procedure straight_29@track
    takes
	track track
    returns track

    #: This procedure will draw a 29 millimeter track to {layout}
    #, starting from {track}.  The track at the end is returned.


procedure straight_45_5@track
    takes
	track track
    returns track

    #: This procedure will draw a 45.5 millimeter track to {layout}
    #, starting from {track}.  The track at the end is returned.


procedure straight_62@track
    takes
	track track
    returns track

    #: This procedure will draw a 62 millimeter track to {layout}
    #, starting from {track}.  The track at the end
    #, of the track is returned.


procedure straight_64@track
    takes
	track track
    returns track

    #: This procedure will draw a 64 millimeter track to {layout}
    #, starting from {track}.  The track at the end is returned.


procedure straight_124@track
    takes
	track track
    returns track

    #: This procedure will draw a 124 millimeter track to {layout}
    #, starting from {track}.  The track at the end is returned.


procedure straight_186@track
    takes
	track track
    returns track

    #: This procedure will draw a 186 millimeter track to {layout}
    #, starting from {track}.  The track at the end is returned.


procedure straight_248@track
    takes
	track track
    returns track

    #: This procedure will draw a 248 millimeter track to {layout}
    #, starting from {track}.  The track at the end is returned.


procedure tick@track
    takes
	track track
    returns_nothing

    #: This procedure will draw a layout tick mark to each side at
    #, {track} using {layout}.


procedure turnout@track
    takes
	track track
	point unsigned
	length unsigned
	radius unsigned
	angle_subtended unsigned
	clockwise logical
    returns track, track

    #: This procedure ...


procedure turnout_6_left@track
    takes
	track track
	point unsigned
    returns track, track

    #: This procedure will produce a number 6 left turnout to {layout}
    #, starting from {track}.  If {point} is 1, {track}
    #, corresponds to entering...


procedure turnout_6_right@track
    takes
	track track
	point unsigned
    returns track, track

    #: This procedure will produce a number 6 right turnout to {layout}
    #, starting from {track}.  If {point} is 1, {track}
    #, corresponds to entering...


procedure uncoupler@track
    takes
	track track
    returns track

    #: This procedure will attach an uncoupler to {track}.
    #, The end track is returned.


procedure vector@track
    takes
	track track
	length float
    returns track

    #: This procedure will draw a straight line from {track} that
    #, is {length} millimeters long.  The {track} at the end-point
    #, of the line is returned.


procedure create@track
    takes
	layout layout
	angle unsigned
	x float
	y float
	z float
	grade float
	tunnel logical
    returns track

    #: This procedure will create and return an track object
    #, with values of {angle}, {x}, {y}, {z}, {grade}, and {tunnel}.