diff --git a/TODO.md b/TODO.md index e711fd4..3b262c1 100644 --- a/TODO.md +++ b/TODO.md @@ -42,7 +42,7 @@ direct HPGL programs and Turtle programs. * Make Turtle library drive the plotter directly, as the HPGL library does. This would eliminate the need to redirect the output to the plotter (using shell I/O redirection) when plotting Turtle programs. -* Add Doxygen comments to the library source. +* Write complete Doxygen comments in the library source. ## Plotting programs * Add new drawings! Especially colouring-in drawings, all-over patterns, diff --git a/turtle.c b/turtle.c index bf741bb..f7b1fed 100644 --- a/turtle.c +++ b/turtle.c @@ -28,6 +28,17 @@ static double Xpos, Ypos; static int Penstate, Pencol; static int Main_flags; + +/** + * @brief Initialise the turtle graphics subsystem + * + * @param dev Device to use, ::DEV_HPGL, ::DEV_PS, ::DEV_BMC, ::DEV_VGA + * @param siz Paper size, ::SIZ_A1, ::SIZ_A2, ::SIZ_A3, ::SIZ_A4, ::SIZ_A5 + * @param ori Drawing orientation (unused), ::ORI_LAND, ::ORI_PORT + * @param flags Option flags, ::FLG_NONE, ::FLG_SLOW, ::FLG_BORD + * + * @return 0 if successful, 1 otherwise + */ int turtle(const int dev, const int siz, const int ori, const int flags) { Pltdev = dev; @@ -169,8 +180,9 @@ int turtle(const int dev, const int siz, const int ori, const int flags) } -/* show --- finish off the plot */ - +/** + * @brief Finish off the plot + */ void show(void) { switch (Pltdev) { @@ -191,8 +203,14 @@ void show(void) } -/* title --- draw a title on the plot */ - +/** + * @brief Draw a title on the plot + * + * @param str String to draw as a title + * @param size Size of text + * @param posn Position of text + * @param flags Flags, ::ITALIC + */ void title(const char str[], const double size, const int posn, const int flags) { int x, y; @@ -264,8 +282,9 @@ void title(const char str[], const double size, const int posn, const int flags) } -/* bottom_left --- move the turtle to the bottom left corner */ - +/** + * @brief Move the turtle to the bottom left corner + */ void bottom_left(void) { Xpos = Minx; @@ -289,8 +308,11 @@ void bottom_left(void) } -/* set_heading --- set the turtle heading to an absolute angle */ - +/** + * @brief Set the turtle heading to an absolute angle + * + * @param deg New heading in degrees + */ void set_heading(const double deg) { Heading = deg; @@ -300,8 +322,11 @@ void set_heading(const double deg) } -/* forward --- move the turtle forward by a given number of millimetres */ - +/** + * @brief Move the turtle forward by a given number of millimetres + * + * @param mm Number of millimetres to move + */ void forward(const double mm) { const double len = mm * Scale; @@ -337,8 +362,11 @@ void forward(const double mm) } -/* turn --- turn the turtle by a given number of degrees */ - +/** + * @brief Turn the turtle by a given number of degrees + * + * @param deg Number of degrees to turn + */ void turn(const double deg) { Heading += deg; @@ -357,16 +385,22 @@ void turn(const double deg) } -/* pen --- raise or lower the pen; only draws when pen down */ - +/** + * @brief Raise or lower the pen; only draws when pen down + * + * @param flag New pen state, ::UP or ::DOWN + */ void pen(const int flag) { Penstate = flag; } -/* colour --- set the pen colour */ - +/** + * @brief Set the pen colour + * + * @param c New pen colour + */ void colour(const int c) { if (Pencol == c) @@ -392,8 +426,11 @@ void colour(const int c) } -/* page_width --- return width of page in millimetres */ - +/** + * @brief Return width of page in millimetres + * + * @return width of page in millimetres + */ double page_width(void) { if (Pltdev != DEV_NONE) @@ -405,8 +442,11 @@ double page_width(void) } -/* page_height --- return height of page in millimetres */ - +/** + * @brief Return height of page in millimetres + * + * @return height of page in millimetres + */ double page_height(void) { if (Pltdev != DEV_NONE) diff --git a/turtle.h b/turtle.h index 279d6a4..f9b8bb2 100644 --- a/turtle.h +++ b/turtle.h @@ -1,42 +1,42 @@ /* turtle --- header file for turtle graphics library 1996-12-15 */ /* Copyright (c) 1996 John Honniball, Froods Software Development */ -#define DEV_NONE (0) -#define DEV_HPGL (1) -#define DEV_BMC (2) -#define DEV_PS (3) -#define DEV_VGA (4) - -#define SIZ_A1 (1) -#define SIZ_A2 (2) -#define SIZ_A3 (3) -#define SIZ_A4 (4) -#define SIZ_A5 (5) - -#define ORI_LAND (0) -#define ORI_PORT (1) - -#define FLG_NONE (0) -#define FLG_BORD (1) -#define FLG_SLOW (2) -#define FLG_RELS (4) - -#define ITALIC (1) - -#define UP (0) -#define DOWN (1) - -#define TOP (1) -#define MID (2) -#define BOT (3) -#define LEFT (4) -#define CENTRE (8) -#define RIGHT (12) - -#define BLACK (1) -#define RED (2) -#define GREEN (3) -#define BLUE (4) +#define DEV_NONE (0) //!< No device selected +#define DEV_HPGL (1) //!< Hewlett-Packard Graphics Language +#define DEV_BMC (2) //!< BMC plotter commands +#define DEV_PS (3) //!< Postscript language +#define DEV_VGA (4) //!< VGA graphics @todo May be obsolete, remove + +#define SIZ_A1 (1) //!< ISO A1 paper size +#define SIZ_A2 (2) //!< ISO A2 paper size +#define SIZ_A3 (3) //!< ISO A3 paper size +#define SIZ_A4 (4) //!< ISO A4 paper size +#define SIZ_A5 (5) //!< ISO A5 paper size + +#define ORI_LAND (0) //!< Drawing orientation landscape @todo Implement this feature +#define ORI_PORT (1) //!< Drawing orientation portrait @todo Implement this feature + +#define FLG_NONE (0) //!< No flags +#define FLG_BORD (1) //!< Flag to draw a border around the plot +#define FLG_SLOW (2) //!< Flag to slow down the drawing to allow for poor pens +#define FLG_RELS (4) //!< Relative size flag + +#define ITALIC (1) //!< Use an italic font (or just a slant) + +#define UP (0) //!< Pen up, turtle moves will not draw anything +#define DOWN (1) //!< Pen down, turtle moves will draw a line + +#define TOP (1) //!< Position of title text: top of page +#define MID (2) //!< Position of title text: middle of page +#define BOT (3) //!< Position of title text: bottom of page +#define LEFT (4) //!< Position of title text: left of page +#define CENTRE (8) //!< Position of title text: centre of page +#define RIGHT (12) //!< Position of title text: right of page + +#define BLACK (1) //!< Pen colour black (only truly correct for BMC plotter) +#define RED (2) //!< Pen colour red (only truly correct for BMC plotter) +#define GREEN (3) //!< Pen colour green (only truly correct for BMC plotter) +#define BLUE (4) //!< Pen colour blue (only truly correct for BMC plotter) int turtle(const int dev, const int siz, const int ori, const int flags); void show(void);