english
version "1.0"
identify "xyz"

#: Copyright (c) 1994, 1995, 1997, 2003 by Wayne C. Gramlich.
#, All rights reserved.
#,
#, Permission to use, copy, modify, distribute, and sell this software
#, for any purpose is hereby granted without fee provided that the above
#, copyright notice and this permission are retained.  The author makes
#, no representations about the suitability of this software for any purpose.
#, It is provided "as is" without express or implied warranty.

module board

#: This module implements a printed circuit board abstraction.

define board				#: The whole board
    record
	board_data board_data		#: Board data
	cell_cache_index unsigned	#: Least recently used index
	cell_cache_table table[cell, cell_cache] #: Images cached at X server
	cell_caches vector[cell_cache]	#: All cell cache objects
	color_artwork xlib_color	#: Artwork color
	color_bartwork xlib_color	#: Back artwork color
	color_back xlib_color		#: Back layer only color
	color_both xlib_color		#: Both front and back layer color
	color_front xlib_color		#: Front layer only color
	color_none xlib_color		#: Background color
	cursor_thickness line_thickness	#: Current thickness for cursor
	cursor_layer layer		#: Current layor for cursor
	cursor_x unsigned		#: Current x location for cursor
	cursor_y unsigned		#: Current y location for cursor
	debug_stream out_stream		#: Debugging output stream
	direction direction		#: Direction of current line
	drawable xlib_drawable		#: Board drawable
	gc xlib_gc			#: GC for "font stuff"
	glyph_table glyph_table		#: The available glyphs to render
	height unsigned			#: Current window height in pixels
	image xlib_image		#: Local image to draw into
	image_cache xlib_drawable	#: Image cache on X server
	is_set logical			#: {true}=>{image} has been set
	length unsigned			#: Length of current line
	pixel_artwork xlib_pixel	#: Artwork pixel
	pixel_bartwork xlib_pixel	#: Back Artwork pixel
	pixel_back xlib_pixel		#: Back layer only pixel
	pixel_both xlib_pixel		#: Both front and back layer pixel
	pixel_front xlib_pixel		#: Front layer only pixel
	pixel_none xlib_pixel		#: Background pixel
	timer_cache_search timer
	timer_image_render timer
	timer_image_send timer
	timer_image_draw timer
	width unsigned			#: Current window width in pixels
	window xlib_window		#: Window to render into
    generate allocate, erase, print

define display_type
    enumeration
	monochrome
	gray_scale
	color
    generate print

define cell_cache
    record
	active logical		#: {true} cell is in use
	key cell		#: Cell used for key
	number unsigned		#: Number of cached image
	usage unsigned		#: Cached image usage count
    generate allocate, erase, identical, print



#: {board} routines:

procedure create@board
    takes
	board_data board_data
	display_type display_type
	glyph_table glyph_table
	screen xlib_screen
	debug_stream out_stream
	timer timer
    returns board

    #: This procedure will create and return a printed ciruit board object.
    #, The board will be rendered into newly allocated window on {screen}.

    #: Allocate some colors:
    #: Allocate a graphics context:
    #: Allocate the local image:

procedure cells_render_changed@board
    takes
	board board
    returns_nothing

    #: This procedure will cause all of the cells that have changed on
    #, {board} to be rerendered.

    #flush@(debug_stream)



procedure cells_unempty_changed@board
    takes
	board board
	x1 unsigned
	y1 unsigned
	x2 unsigned
	y2 unsigned
    returns_nothing

    #: This procedure will mark each unempty cell in {board} from ({x1}, {y1})
    #, to ({x2}, {y2}) as changed.


procedure cell_render@board
    takes
	board board
	x unsigned
	y unsigned
    returns_nothing

    #: This procedure will redraw the cell at ({x}, {y}) in {board}.


procedure cursor_layer@board
    takes
	board board
	layer layer
    returns_nothing

    #: This procedure will set the cursor layer of {board} to {layer}.


procedure cursor_position@board
    takes
	board board
	x unsigned
	y unsigned
    returns_nothing

    #: This procedure will set the cursor postition of {board} to ({x}, {y}).


procedure cursor_refresh@board
    takes
	board board
    returns_nothing

    #: This procedure will ensure that the cursor is properly displayed.


procedure cursor_thickness@board
    takes
	board board
	thickness line_thickness
    returns_nothing

    #: This procedure will set the cursor thickness of {board} to {thickness}.


procedure render@board
    takes
	board board
	chunk chunk
	layer layer
    returns_nothing

    #: This procedure will render {chunk} on {layer} for {board}.


procedure chunk_overlay@board
    takes
	board board
	chunk chunk
	color_only xlib_pixel
    returns_nothing

    #: This procedure will overlay the {chunk} into {board}.{image} using
    #, {color_only}.  Any pixels in {board}.{image} that are already set
    #, are set to {board}.{pixel_both}.


procedure direction_length_compute@board
    takes
	board board
	x1 unsigned
	y1 unsigned
	x2 unsigned
	y2 unsigned
    returns_nothing

    #: This procedure will determine the closest line connecting cells
    #,({x1}, {y1}) and ({x2}, {y2}) and the associated length and
    #, store them into the {direction} and {length} fields of {board}.

    #, direction as a multiple return.  Unfortunately, there is a bug
    #, in the C version of the STIPPLE compiler the prevents the return
    #, of an enumeration type.  Hence, the return values are stuffed
    #, into fields inside of the {board} data structure.  Not pretty,
    #, but it gets the job done.

    # Return



procedure raster_write@board
    takes
	board board
	print_file string
	layer string
	monochrome logical
	inverted_image logical
	out_stream out_stream
	timer timer
    returns_nothing

    #: This procedure will write {board_data} to {print_file}
    #, in Sun raster file format.  If {print_file} is "-", the
    #, output is directed to {out_stream}.  If {layer} is non-empty,
    #, only that layer is output.  If {monochome} is {true}, all
    #, colors are output as black and the background as white;
    #, otherwise, a color output is generated.  If {inverted_image}
    #, is {true}, an inverted image is output; this includes
    #, inverting character strings so that they are still readable.


procedure big_endian_word_put@unsigned
    takes
	word unsigned
	out_stream out_stream
    returns_nothing

    #: This routine will output {word} to {out_stream} in big
    #, endian (most-significant byte first).


procedure distance_compute
    takes
	x1 unsigned
	y1 unsigned
	x2 unsigned
	y2 unsigned
    returns unsigned

    #: This procedure will return a distance metric for the distance between
    #, {({x1}, {y1})} and {({x2}, {y2})}.


procedure color_select@display_type
    takes
	display_type display_type
	color_map xlib_color_map
	color_color_name string
	gray_scale_color_name string
	monochrome_color_name string
    returns xlib_color