english
version "1.0"
identify "@(#)glyph.sts 1.10 96/03/22"

#: Copyright (c) 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 glyph

#: This module implements code for manipulating the font used to
#, render printed circuit boards on the screen and/or printer.

define chunk				#: A cell sized chunk of a glyph
    record
	glyph glyph			#: The glyph to use
	x unsigned			#: X position/offset
	y unsigned			#: Y position/offset
    generate allocate, equal, erase, hash, print

define glyph				#: An image that can be rendered
    record
	bitmap vector[vector[logical]]	#: Bitmap representation of glyph
	file glyph_file			#: {glyph_file} containing {glyph}
	height unsigned			#: Glyph height
	id unsigned			#: Unique identification number
	leads vector[glyph_lead]	#: Any leads to connect to
	marked logical			#: {true}=>needed in output file
	name string			#: Glyph name
	width unsigned			#: Glyph width
    generate address_get, allocate, erase, identical, print

define glyph_file			#: A file of glyphs
    record
	base_name string		#: Base name of file
	cell_height unsigned		#: Cell height
	cell_width unsigned		#: Cell width
	marked logical			#: {true}=>needed in output file
	glyph_table glyph_table		#: {glyph_table} containing file
	glyphs vector[glyph]		#: Glyphs from file
    generate allocate, erase, identical, print

define glyph_lead			#: A wire connection point on glyph
    record
	glyph glyph			#: Glyph that lead is part of
	name string			#: Lead name (or ??)
	x unsigned			#: X coordinate
	y unsigned			#: Y coordinate
    generate allocate, erase, identical, print

define glyph_table			#: A table of glyphs
    record
	all_files vector[glyph_file]	#: All of the files in the table
	all_glyphs vector[glyph]	#: List of each glyph in table
	geometry geometry		#: Geometry of cells
	error_stream out_stream		#: Stream used for error messages
	file_table table[string, glyph_file] #: Table of all glyph files
	marked_files vector[glyph_file]	#: All marked files in the table
	marked_glyphs vector[glyph]	#: All marked glyphs
	name_table table[string, glyph]	#: Name to glyph table
    generate allocate, erase, identical, print



#: {chunk} procedures:

procedure copy@chunk
    takes
	chunk chunk
    returns chunk

    #: This procedure will return a copy of {chunk}.


procedure create@chunk
    takes
	glyph glyph
	x unsigned
	y unsigned
    returns chunk

    #: This procedure will create and return a new {chunk} object
    #, that contains {glyph}, {x}, and {y}.


procedure compare@chunk
    takes
	chunk1 chunk
	chunk2 chunk
    returns integer

    #: This procedeure will return -1, 0, or 1 depending upon whether
    #, {chunk1} is less than, equal to, or greater than
    #, {chunk2}.


procedure invert@chunk
    takes
	chunk chunk
    returns chunk

    #: This procedure will return an inverted version of {chunk}.


procedure read@chunk
    takes
	in_stream in_stream
	glyph_table glyph_table
    returns chunk

    #: This procedure will create and return a new {chunk} object
    #, whose contents are initialized from {in_stream}.


procedure rotate@chunk
    takes
	chunk chunk
    returns chunk

    #: This procedure will return a copy of {chunk} where the glyph
    #, has been rotated 90 degrees.


procedure write@chunk
    takes
	chunk chunk
	out_stream out_stream
    returns_nothing

    #: This procedure will write {chunk} to {out_stream} such that it
    #, can be subsequently read in using {read}@{chunk}.


#: {glyph} procedures:

procedure copy@glyph
    takes
	glyph glyph
    returns glyph

    #: This procedure will return a "copy" of {glyph}.

    #, does is return {glyph}.


procedure create@glyph
    takes
	bitmap vector[vector[logical]]
	file glyph_file
	height unsigned
	id unsigned
	leads vector[glyph_lead]
	name string
	width unsigned
    returns glyph

    #: This procedure will create and return a new {glpyh} object
    #, that contains {bitmap}, {file}, {height}, {id}, {leads},
    #, {name}, and {width}.


procedure dump@glyph
    takes
	glyph glyph
	out_stream out_stream
    returns_nothing

    #: This procedure will output {glyph} to {out_stream}.


procedure equal@glyph
    takes
	glyph1 glyph
	glyph2 glyph
    returns logical

    #: This procedure will return {true} if {glyph1} is equal to {glyph2}.

    #, is good enough.


procedure hash@glyph
    takes
	glyph glyph
    returns unsigned

    #: This procedure will return a hash value for {glyph}.

    #, be used.


procedure invert@glyph
    takes
	glyph glyph
    returns glyph

    #: This procedure will return an inverted version of {glyph}.


procedure mark@glyph
    takes
	glyph glyph
    returns_nothing

    #: This procedure will mark {glyph} as needed for in the eventual
    #, output file.


procedure mirror@glyph
    takes
	glyph glyph
    returns_nothing

    #: This procedure will cause {glyph} to mirrored about its vertical
    #, axis.  This procedure violates the immutable nature of {glyph}'s.


procedure read@glyph
    takes
	in_stream in_stream
	file glyph_file
	line string
	error_stream out_stream
    returns glyph

    #: This procedure will read in and return one {glyph} from
    #, {in_stream}.  The {glyph} is and {line} is used as a
    #, temporary buffer.


procedure rotate@glyph
    takes
	glyph glyph
	file glyph_file
    returns glyph

    #: This procedure will rotate {glyph} 90 degrees clockwise and
    #, return a new glyph.


#: {glyph_file} procedures:

procedure copy@glyph_file
    takes
	glyph_file glyph_file
    returns glyph_file

    #: This procedure will return a copy of {glyph_file}.  Since {glyph_file}
    #, objects are essentially immutable, no real copy takes place.


procedure equal@glyph_file
    takes
	glyph_file1 glyph_file
	glyph_file2 glyph_file
    returns logical

    #: This procedure returns {true} if {glyph_file1} is equal to
    #, {glyph_file2}, and {false} otherwise.

    #, suffices.


procedure hash@glyph_file
    takes
	glyph_file glyph_file
    returns unsigned

    #: This procedure will return a hash value based on {glyph_file}.


procedure read@glyph_file
    takes
	base_name string
	glyph_table glyph_table
	error_stream out_stream
    returns glyph_file

    #: This procedure will read in and return a {glyph_file} object from
    #, the file name constructed using {base_name} and the cell height
    #, and width contained in {glyph_table}.  If any errors occur reading
    #, the glyph file, an error message is output to {error_stream} and
    #, ??@{glyph_file} is returned.


#: {glyph_table} procedures:

procedure built_in@glyph_table
    takes
	glyph_table glyph_table
	name string
    returns chunk

    #: This procedure will create and return the chunk for the built in
    #, glyph named {name} in {glyph_table}.


procedure create@glyph_table
    takes
	geometry geometry
	error_stream out_stream
    returns glyph_table

    #: This procedure will create and return an empty {glyph_table} object
    #, using {geometry} to get the cell size.


procedure fetch1@glyph_table
    takes
	glyph_table glyph_table
	name string
    returns glyph

    #: This procedure will return the {glyph} associated with {name} in
    #, {glyph_table}.  If there is no {glyph} associated with {name} in
    #, {glyph_table}, ??@{glyph} is returned.


procedure read@glyph_table
    takes
	glyph_table glyph_table
	in_stream in_stream
	error_stream out_stream
    returns logical

    #: This procedure will read in information from {in_stream} and
    #, store it in {glyph_table}.  The {glyph_table} data should have
    #, been previously written out using {write}@{glyph_table}.  If
    #, any errors occur, an error message is output to {error_stream}
    #, and {true} is returned; otherwise {false} is returned.


procedure unmark@glyph_table
    takes
	glyph_table glyph_table
    returns_nothing

    #: This procedure will unmark any glyphs in {glyph_table} that have
    #, been previously marked with {glyph_mark}@{glyph_table}.


procedure write@glyph_table
    takes
	glyph_table glyph_table
	out_stream out_stream
    returns_nothing

    #: This procedure will output {glyph_table} to {out_stream} suitable
    #, for reading in using {read}@{glyph_table}.  The needed glyphs
    #, should have been previously marked using {glyph_mark}@{glyph_table}.