From 5c3b299eb06c3841566bf001f0cd7347499a5bed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Tue, 24 Jul 2018 14:42:28 +0200 Subject: [PATCH] minor fixes and doxygen Documentation started --- cairo-output/cairo-output.c | 40 ++++++++- cairo-output/cairo-output.h | 21 ++++- doxygen/Doxyconfig | 4 +- gds-parser/gds-parser.c | 159 +++++++++++++++++++++++++++++++++--- gds-parser/gds-parser.h | 18 ++++ gds-parser/gds-types.h | 102 ++++++++++++++++++----- latex-output/latex-output.h | 24 +++++- 7 files changed, 329 insertions(+), 39 deletions(-) diff --git a/cairo-output/cairo-output.c b/cairo-output/cairo-output.c index 21abaf2..062c0fd 100644 --- a/cairo-output/cairo-output.c +++ b/cairo-output/cairo-output.c @@ -16,6 +16,15 @@ * You should have received a copy of the GNU General Public License * along with GDSII-Converter. If not, see . */ + /** + * @file cairo-output.c + * @brief Output renderer for Cairo PDF export + * @author Mario Hüttel + */ + +/** @addtogroup Cairo-Renderer + * @{ + */ #include "cairo-output.h" #include @@ -23,12 +32,20 @@ #include #include +/** + * @brief The cairo_layer struct + * Each rendered layer is represented by this struct. + */ struct cairo_layer { - cairo_t *cr; - cairo_surface_t *rec; - struct layer_info *linfo; + cairo_t *cr; /**< @brief cairo context for layer*/ + cairo_surface_t *rec; /**< @brief Recording surface to hold the layer */ + struct layer_info *linfo; /**< @brief Reference to layer information */ }; +/** + * @brief Revert the last transformation on all layers + * @param layers Pointer to #cairo_layer structures + */ static void revert_inherited_transform(struct cairo_layer *layers) { int i; @@ -40,6 +57,15 @@ static void revert_inherited_transform(struct cairo_layer *layers) } } +/** + * @brief Applies transformation to all layers + * @param layers Array of layers + * @param origin Origin translation + * @param magnification Scaling + * @param flipping Mirror image on x-axis before rotating + * @param rotation Rotattion in degrees + * @param scale Scale the image down by. Only used for sclaing origin coordinates. Not applied to layer. + */ static void apply_inherited_transform_to_all_layers(struct cairo_layer *layers, const struct gds_point *origin, double magnification, @@ -64,6 +90,12 @@ static void apply_inherited_transform_to_all_layers(struct cairo_layer *layers, } } +/** + * @brief render_cell Render a cell with its sub-cells + * @param cell Cell to render + * @param layers Cell will be rendered into these layers + * @param scale sclae image down by this factor + */ static void render_cell(struct gds_cell *cell, struct cairo_layer *layers, double scale) { GList *instance_list; @@ -246,3 +278,5 @@ ret_clear_layers: printf("cairo export finished. It might still be buggy!\n"); } + +/** @} */ diff --git a/cairo-output/cairo-output.h b/cairo-output/cairo-output.h index cf7aa4f..069372c 100644 --- a/cairo-output/cairo-output.h +++ b/cairo-output/cairo-output.h @@ -16,15 +16,32 @@ * You should have received a copy of the GNU General Public License * along with GDSII-Converter. If not, see . */ - +/** + * @file cairo-output.h + * @brief Header File for Cairo output renderer + * @author Mario Hüttel + */ #ifndef __CAIRO_OUTPUT_H__ #define __CAIRO_OUTPUT_H__ #include "../layer-selector.h" #include "../gds-parser/gds-types.h" -#define MAX_LAYERS (300) +/** @addtogroup Cairo-Renderer + * @{ + */ +#define MAX_LAYERS (300) /**< \brief Maximum layer count the output renderer can process. Typically GDS only specifies up to 255 layers.*/ + +/** + * @brief Render \p cell to a PDF file specified by \p pdf_file + * @param cell Toplevel cell to render + * @param layer_infos List of layer information. Specifies color and layer stacking + * @param pdf_file Output file + * @param scale Scale the output image down by \p scale + */ void cairo_render_cell_to_pdf(struct gds_cell *cell, GList *layer_infos, char *pdf_file, double scale); +/** @} */ + #endif /* __CAIRO_OUTPUT_H__ */ diff --git a/doxygen/Doxyconfig b/doxygen/Doxyconfig index 2d165f3..90c8326 100644 --- a/doxygen/Doxyconfig +++ b/doxygen/Doxyconfig @@ -454,7 +454,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, @@ -865,7 +865,7 @@ FILE_PATTERNS = *.c \ # be searched for input files as well. # The default value is: NO. -RECURSIVE = NO +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a diff --git a/gds-parser/gds-parser.c b/gds-parser/gds-parser.c index a39e9c8..6adcaa3 100644 --- a/gds-parser/gds-parser.c +++ b/gds-parser/gds-parser.c @@ -18,14 +18,27 @@ */ /* + + */ + + +/** + * @file gds_parser.h + * @brief Header file for the GDS-Parser + * @author Mario Hüttel + * * What's missing? - A lot: - * Support for Boxes * Support for 4 Byte real * Support for pathtypes * Support for datatypes (only layer so far) * etc... */ +/** + * @addtogroup GDS-Parser + * @{ + */ + #include "gds-parser.h" #include @@ -35,10 +48,10 @@ #include #include -#define GDS_ERROR(fmt, ...) printf("[PARSE_ERROR] " fmt "\n", ##__VA_ARGS__) -#define GDS_WARN(fmt, ...) printf("[PARSE_WARNING] " fmt "\n", ##__VA_ARGS__) +#define GDS_ERROR(fmt, ...) printf("[PARSE_ERROR] " fmt "\n", ##__VA_ARGS__) /**< @brief Print GDS error*/ +#define GDS_WARN(fmt, ...) printf("[PARSE_WARNING] " fmt "\n", ##__VA_ARGS__) /**< @brief Print GDS warning */ -enum record { +enum gds_record { INVALID = 0x0000, HEADER = 0x0002, BGNLIB = 0x0102, @@ -63,6 +76,13 @@ enum record { PATHTYPE = 0x2102 }; +/** + * @brief Name cell reference + * @param cell_inst Cell reference + * @param bytes Length of name + * @param data Name + * @return 0 if successful + */ static int name_cell_ref(struct gds_cell_instance *cell_inst, unsigned int bytes, char *data) { @@ -73,7 +93,7 @@ static int name_cell_ref(struct gds_cell_instance *cell_inst, return -1; } data[bytes] = 0; // Append '0' - len = strlen(data); + len = (int)strlen(data); if (len > CELL_NAME_MAX-1) { GDS_ERROR("Cell name '%s' too long: %d\n", data, len); return -1; @@ -86,6 +106,11 @@ static int name_cell_ref(struct gds_cell_instance *cell_inst, return 0; } +/** + * @brief Convert GDS 8-byte real to double + * @param data 8 Byte GDS real + * @return result + */ static double gds_convert_double(const char *data) { bool sign_bit; @@ -126,6 +151,11 @@ static double gds_convert_double(const char *data) return ret_val; } +/** + * @brief Convert GDS INT32 to int + * @param data Buffer containing the int + * @return result + */ static signed int gds_convert_signed_int(const char *data) { int ret; @@ -142,6 +172,11 @@ static signed int gds_convert_signed_int(const char *data) return ret; } +/** + * @brief Convert GDS INT16 to int16 + * @param data Buffer containing the INT16 + * @return result + */ static int16_t gds_convert_signed_int16(const char *data) { if (!data) { @@ -152,6 +187,11 @@ static int16_t gds_convert_signed_int16(const char *data) (((int16_t)(data[1]) & 0xFF) << 0)); } +/** + * @brief Convert GDS UINT16 String to uint16 + * @param data Buffer containing the uint16 + * @return result + */ static uint16_t gds_convert_unsigend_int16(const char *data) { if (!data) { @@ -162,6 +202,12 @@ static uint16_t gds_convert_unsigend_int16(const char *data) (((uint16_t)(data[1]) & 0xFF) << 0)); } +/** + * @brief Append library to list + * @param curr_list List containing gds_library elements. May be NULL. + * @param library_ptr Return of newly created library. + * @return Newly created list pointer + */ static GList *append_library(GList *curr_list, struct gds_library **library_ptr) { struct gds_library *lib; @@ -180,6 +226,13 @@ static GList *append_library(GList *curr_list, struct gds_library **library_ptr) return g_list_append(curr_list, lib); } +/** + * @brief Append graphics to list + * @param curr_list List containing gds_graphics elements. May be NULL + * @param type Type of graphics + * @param graphics_ptr newly created graphic is written here + * @return new list pointer + */ static GList *append_graphics(GList *curr_list, enum graphics_type type, struct gds_graphics **graphics_ptr) { @@ -202,6 +255,13 @@ static GList *append_graphics(GList *curr_list, enum graphics_type type, return g_list_append(curr_list, gfx); } +/** + * @brief Appends vertext List + * @param curr_list List containing gds_point elements. May be NULL. + * @param x x-coordinate of new point + * @param y y-coordinate of new point + * @return new Pointer to List. + */ static GList *append_vertex(GList *curr_list, int x, int y) { struct gds_point *vertex; @@ -215,6 +275,14 @@ static GList *append_vertex(GList *curr_list, int x, int y) return g_list_append(curr_list, vertex); } +/** + * @brief append_cell Append a gds_cell to a list + * + * Usage similar to append_cell_ref(). + * @param curr_list List containing gds_cell elements. May be NULL + * @param cell_ptr newly created cell + * @return new pointer to list + */ static GList *append_cell(GList *curr_list, struct gds_cell **cell_ptr) { struct gds_cell *cell; @@ -233,6 +301,14 @@ static GList *append_cell(GList *curr_list, struct gds_cell **cell_ptr) return g_list_append(curr_list, cell); } +/** + * @brief Append a cell reference to the reference GList. + * + * Appends a new gds_cell_instance to \p curr_list and returns the new element via \p instance_ptr + * @param curr_list List of gds_cell_instance elements. May be NULL + * @param instance_ptr newly created element + * @return new GList pointer + */ static GList *append_cell_ref(GList *curr_list, struct gds_cell_instance **instance_ptr) { struct gds_cell_instance *inst; @@ -254,6 +330,13 @@ static GList *append_cell_ref(GList *curr_list, struct gds_cell_instance **insta return g_list_append(curr_list, inst); } +/** + * @brief Name a gds_library + * @param current_library Library to name + * @param bytes Lenght of name + * @param data Name + * @return 0 if successful + */ static int name_library(struct gds_library *current_library, unsigned int bytes, char *data) { @@ -265,7 +348,7 @@ static int name_library(struct gds_library *current_library, } data[bytes] = 0; // Append '0' - len = strlen(data); + len = (int)strlen(data); if (len > CELL_NAME_MAX-1) { GDS_ERROR("Library name '%s' too long: %d\n", data, len); return -1; @@ -277,6 +360,14 @@ static int name_library(struct gds_library *current_library, return 0; } +/** + * @brief Names a gds_cell + * @param cell Cell to name + * @param bytes Length of name + * @param data Name + * @param lib Library in which \p cell is located + * @return 0 id successful + */ static int name_cell(struct gds_cell *cell, unsigned int bytes, char *data, struct gds_library *lib) { @@ -302,7 +393,13 @@ static int name_cell(struct gds_cell *cell, unsigned int bytes, return 0; } - +/** + * @brief Search for cell reference \p gcell_ref in \p glibrary + * + * Search cell referenced by \p gcell_ref inside \p glibrary and update gds_cell_instance::cell_ref with found #gds_cell + * @param gcell_ref gpointer cast of struct gds_cell_instance * + * @param glibrary gpointer cast of struct gds_library * + */ static void parse_reference_list(gpointer gcell_ref, gpointer glibrary) { struct gds_cell_instance *inst = (struct gds_cell_instance *)gcell_ref; @@ -329,6 +426,12 @@ static void parse_reference_list(gpointer gcell_ref, gpointer glibrary) GDS_WARN("referenced cell could not be found in library"); } +/** + * @brief Scans cell references inside cell + This function searches all the references in \p gcell and updates the gds_cell_instance::cell_ref field in each instance + * @param gcell pointer cast of #gds_cell * + * @param library Library where the cell references are searched in + */ static void scan_cell_reference_dependencies(gpointer gcell, gpointer library) { struct gds_cell *cell = (struct gds_cell *)gcell; @@ -340,6 +443,13 @@ static void scan_cell_reference_dependencies(gpointer gcell, gpointer library) } +/** + * @brief Scans library's cell references + * + * This function searches all the references between cells and updates the gds_cell_instance::cell_ref field in each instance + * @param library_list_item List containing #gds_library elements + * @param user not used + */ static void scan_library_references(gpointer library_list_item, gpointer user) { struct gds_library *lib = (struct gds_library *)library_list_item; @@ -348,6 +458,13 @@ static void scan_library_references(gpointer library_list_item, gpointer user) g_list_foreach(lib->cells, scan_cell_reference_dependencies, lib); } +/** + * @brief gds_parse_date + * @param buffer Buffer that contains the GDS Date field + * @param length Length of \p buffer + * @param mod_date Modification Date + * @param access_date Last Access Date + */ static void gds_parse_date(const char *buffer, int length, struct gds_time_field *mod_date, struct gds_time_field *access_date) { @@ -390,7 +507,7 @@ int parse_gds_from_file(const char *filename, GList **library_list) int run = 1; FILE *gds_file = NULL; uint16_t rec_data_length; - enum record rec_type; + enum gds_record rec_type; struct gds_library *current_lib = NULL; struct gds_cell *current_cell = NULL; struct gds_graphics *current_graphics = NULL; @@ -628,10 +745,10 @@ int parse_gds_from_file(const char *filename, GList **library_list) gds_parse_date(workbuff, read, ¤t_cell->mod_time, ¤t_cell->access_time); break; case LIBNAME: - name_library(current_lib, read, workbuff); + name_library(current_lib, (unsigned int)read, workbuff); break; case STRNAME: - name_cell(current_cell, read, workbuff, current_lib); + name_cell(current_cell, (unsigned int)read, workbuff, current_lib); break; case XY: if (current_s_reference) { @@ -742,22 +859,38 @@ int parse_gds_from_file(const char *filename, GList **library_list) return run; } +/** + * @brief delete_cell_inst_element + * @param cell_inst + */ static void delete_cell_inst_element(struct gds_cell_instance *cell_inst) { free(cell_inst); } +/** + * @brief delete_vertex + * @param vertex + */ static void delete_vertex(struct gds_point *vertex) { free(vertex); } +/** + * @brief delete_graphics_obj + * @param gfx + */ static void delete_graphics_obj(struct gds_graphics *gfx) { g_list_free_full(gfx->vertices, (GDestroyNotify)delete_vertex); free(gfx); } +/** + * @brief delete_cell_element + * @param cell + */ static void delete_cell_element(struct gds_cell *cell) { g_list_free_full(cell->child_cells, (GDestroyNotify)delete_cell_inst_element); @@ -765,6 +898,10 @@ static void delete_cell_element(struct gds_cell *cell) free(cell); } +/** + * @brief delete_library_element + * @param lib + */ static void delete_library_element(struct gds_library *lib) { g_list_free(lib->cell_names); @@ -780,3 +917,5 @@ int clear_lib_list(GList **library_list) *library_list = NULL; return 0; } + +/** @} */ diff --git a/gds-parser/gds-parser.h b/gds-parser/gds-parser.h index f5f571f..82331ec 100644 --- a/gds-parser/gds-parser.h +++ b/gds-parser/gds-parser.h @@ -17,6 +17,17 @@ * along with GDSII-Converter. If not, see . */ +/** + * @file gds_parser.h + * @brief Header file for the GDS-Parser + * @author Mario Hüttel + */ + +/** + * @addtogroup GDS-Parser + * @{ + */ + #ifndef __GDSPARSE_H__ #define __GDSPARSE_H__ @@ -24,6 +35,13 @@ #include "gds-types.h" int parse_gds_from_file(const char *filename, GList **library_array); +/** + * @brief Deletes all libraries including cells, references etc. + * @param Pointer to a list of #gds_library. Is set to NULL after completion. + * @return 0 + */ int clear_lib_list(GList **library_list); +/** @} */ + #endif /* __GDSPARSE_H__ */ diff --git a/gds-parser/gds-types.h b/gds-parser/gds-types.h index 0a88b3e..8f34501 100644 --- a/gds-parser/gds-types.h +++ b/gds-parser/gds-types.h @@ -1,21 +1,67 @@ +/* + * GDSII-Converter + * Copyright (C) 2018 Mario Hüttel + * + * This file is part of GDSII-Converter. + * + * GDSII-Converter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation. + * + * GDSII-Converter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with GDSII-Converter. If not, see . + */ + +/** + * @file gds-types.h + * @brief Defines types and macros used by the GDS-Parser + * @author Mario Hüttel + */ + +/** + * @addtogroup GDS-Parser + * @{ + */ + #ifndef __GDS_TYPES_H__ #define __GDS_TYPES_H__ #include #include -#define CELL_NAME_MAX (100) -#define MIN(a,b) (((a) < (b)) ? (a) : (b)) -#define MAX(a,b) (((a) > (b)) ? (a) : (b)) +#define CELL_NAME_MAX (100) /**< @brief Maximum length of a gds_cell::name or a gds_library::name */ +#define MIN(a,b) (((a) < (b)) ? (a) : (b)) /**< @brief Find return smaller number */ +#define MAX(a,b) (((a) > (b)) ? (a) : (b)) /**< @brief Find return bigger number */ -enum graphics_type {GRAPHIC_PATH = 0, GRAPHIC_POLYGON = 1, GRAPHIC_BOX}; -enum path_type {PATH_FLUSH = 0, PATH_ROUNDED = 1, PATH_SQUARED = 2}; +/** @brief Types of graphic objects */ +enum graphics_type +{ + GRAPHIC_PATH = 0, /**< @brief Path. Esentially a line */ + GRAPHIC_POLYGON = 1, /**< @brief An arbitrary polygon */ + GRAPHIC_BOX = 2 /**< @brief A rectangle. @warning Implementation in renderers might be buggy!*/ +}; +/** + * @brief Defines the line caps of a path + */ +enum path_type {PATH_FLUSH = 0, PATH_ROUNDED = 1, PATH_SQUARED = 2}; /**< Path line caps */ + +/** + * @brief A point in the 2D plane. Sometimes references as vertex + */ struct gds_point { int x; int y; }; +/** + * @brief Date information for cells and libraries + */ struct gds_time_field { uint16_t year; uint16_t month; @@ -25,39 +71,53 @@ struct gds_time_field { uint16_t second; }; +/** + * @brief A GDS graphics object + */ struct gds_graphics { - enum graphics_type gfx_type; - GList *vertices; - enum path_type path_render_type; - int width_absolute; - int16_t layer; + enum graphics_type gfx_type; /**< \brief Type of graphic */ + GList *vertices; /**< @brief List of #gds_point */ + enum path_type path_render_type; /**< @brief Line cap */ + int width_absolute; /**< @brief Width. Not used for objects other than paths */ + int16_t layer; /**< @brief Layer the graphic object is on */ uint16_t datatype; }; +/** + * @brief This represents an instanc of a cell inside another cell + */ struct gds_cell_instance { - char ref_name[CELL_NAME_MAX]; - struct gds_cell *cell_ref; - struct gds_point origin; - int flipped; - double angle; - double magnification; + char ref_name[CELL_NAME_MAX]; /**< @brief Name of referenced cell */ + struct gds_cell *cell_ref; /**< @brief Referenced gds_cell structure */ + struct gds_point origin; /**< @brief Origin */ + int flipped; /**< @brief Mirrored on x-axis before rotation */ + double angle; /**< @brief Angle of rotation (counter clockwise) in degrees */ + double magnification; /**< @brief magnification */ }; +/** + * @brief A Cell inside a gds_library + */ struct gds_cell { char name[CELL_NAME_MAX]; struct gds_time_field mod_time; struct gds_time_field access_time; - GList *child_cells; - GList *graphic_objs; + GList *child_cells; /**< @brief List of #gds_cell_instance elements */ + GList *graphic_objs; /**< @brief List of #gds_graphics */ }; +/** + * @brief GDS Toplevel library + */ struct gds_library { char name[CELL_NAME_MAX]; struct gds_time_field mod_time; struct gds_time_field access_time; - double unit_to_meters; - GList *cells; - GList *cell_names; + double unit_to_meters; /**< @warning not yet implemented */ + GList *cells; /**< List of #gds_cell that contains all cells in this library*/ + GList *cell_names /**< List of strings that contains all cell names */; }; +/** @} */ + #endif /* __GDS_TYPES_H__ */ diff --git a/latex-output/latex-output.h b/latex-output/latex-output.h index f88b16e..47daa88 100644 --- a/latex-output/latex-output.h +++ b/latex-output/latex-output.h @@ -17,17 +17,39 @@ * along with GDSII-Converter. If not, see . */ +/** + * @file latex-output.h + * @brief LaTeX output renderer + * @author Mario Hüttel + */ + #ifndef __LATEX_OUTPUT_H__ #define __LATEX_OUTPUT_H__ +/** + * @addtogroup LaTeX-Renderer + * @{ + */ + #include "../gds-parser/gds-types.h" #include #include #include "../layer-selector.h" -#define LATEX_LINE_BUFFER_KB (10) +#define LATEX_LINE_BUFFER_KB (10) /**< @brief Buffer for LaTeX Code line in KiB */ +/** + * @brief Render \p cell to LateX/TikZ code + * @param cell Cell to render + * @param layer_infos Layer information + * @param tex_file Already opened file to write data in + * @param scale Scale image down by this value + * @param create_pdf_layers Optional content groups used + * @param standalone_document document can be compiled standalone + */ void latex_render_cell_to_code(struct gds_cell *cell, GList *layer_infos, FILE *tex_file, double scale, gboolean create_pdf_layers, gboolean standalone_document); +/** @} */ + #endif /* __LATEX_OUTPUT_H__ */