From 469568862b1330a6dbdcbaaddaee1dcf84f19e1d Mon Sep 17 00:00:00 2001 From: Hermann Kraus Date: Tue, 24 Jan 2012 18:23:33 +0100 Subject: [PATCH] Add documentation. --- docs/textrendering.gv | 20 +++++++++ include/mapnik/text_path.hpp | 26 ++++++++--- include/mapnik/text_placements.hpp | 69 +++++++++++++++++++++++++++--- include/mapnik/text_processing.hpp | 15 ++++--- 4 files changed, 112 insertions(+), 18 deletions(-) create mode 100644 docs/textrendering.gv diff --git a/docs/textrendering.gv b/docs/textrendering.gv new file mode 100644 index 000000000..285ec4cb2 --- /dev/null +++ b/docs/textrendering.gv @@ -0,0 +1,20 @@ +#process with: dot textrendering.gv -Tpng > textrendering.png +digraph textrendering { +# Classes without important virtual members: Round +# Classes with important virtual members: Rect +# Pointers [style=dashed] +# Red: function is called + text_placements[shape=box] + text_placement_info[shape=box] + Renderer + + TextSymbolizer -> text_placements [label="placement_options_", style=dashed] + text_placements -> text_symbolizer_properties [label="properties"] + text_placements -> text_placement_info [label="get_placement_info()", style=dashed] + text_placement_info -> text_symbolizer_properties [label="properties"] + text_placement_info -> text_path [label="placements", style=dashed] + text_symbolizer_properties -> text_processor [label="processor"] + text_path -> Renderer [label="used by"] + Renderer -> text_placement_info [color=red, label="init()"] + +} \ No newline at end of file diff --git a/include/mapnik/text_path.hpp b/include/mapnik/text_path.hpp index a9e232ae2..b7d7daaf1 100644 --- a/include/mapnik/text_path.hpp +++ b/include/mapnik/text_path.hpp @@ -117,7 +117,9 @@ public: } }; -struct text_path : boost::noncopyable + +/** List of all characters and their positions and formats for a placement. */ +class text_path : boost::noncopyable { struct character_node { @@ -139,41 +141,51 @@ struct text_path : boost::noncopyable } }; + int itr_; +public: typedef std::vector character_nodes_t; + character_nodes_t nodes_; double starting_x; double starting_y; - character_nodes_t nodes_; - int itr_; - std::pair string_dimensions; +// std::pair string_dimensions; text_path() - : starting_x(0), - starting_y(0), - itr_(0) {} + : itr_(0), + starting_x(0), + starting_y(0) + + { + + } ~text_path() {} + /** Adds a new char to the list. */ void add_node(int c, double x, double y, double angle, char_properties *format) { nodes_.push_back(character_node(c, x, y, angle, format)); } + /** Return node. Always returns a new node. Has no way to report that there are no more nodes. */ void vertex(int *c, double *x, double *y, double *angle, char_properties **format) { nodes_[itr_++].vertex(c, x, y, angle, format); } + /** Start again at first node. */ void rewind() { itr_ = 0; } + /** Number of nodes. */ int num_nodes() const { return nodes_.size(); } + /** Delete all nodes. */ void clear() { nodes_.clear(); diff --git a/include/mapnik/text_placements.hpp b/include/mapnik/text_placements.hpp index 13d67b8f9..fdb6530dc 100644 --- a/include/mapnik/text_placements.hpp +++ b/include/mapnik/text_placements.hpp @@ -92,10 +92,13 @@ enum justify_alignment DEFINE_ENUM( justify_alignment_e, justify_alignment ); +/** Contains all text symbolizer properties which are not directly related to text formating. */ struct text_symbolizer_properties { text_symbolizer_properties(); + /** Load all values and also the ```processor``` object from XML ptree. */ void set_values_from_xml(boost::property_tree::ptree const &sym, std::map const & fontsets); + /** Save all values to XML ptree (but does not create a new parent node!). */ void to_xml(boost::property_tree::ptree &node, bool explicit_defaults, text_symbolizer_properties const &dfl=text_symbolizer_properties()) const; //Per symbolizer options @@ -105,71 +108,124 @@ struct text_symbolizer_properties horizontal_alignment_e halign; justify_alignment_e jalign; vertical_alignment_e valign; - unsigned label_spacing; // distance between repeated labels on a single geometry - unsigned label_position_tolerance; //distance the label can be moved on the line to fit, if 0 the default is used + /** distance between repeated labels on a single geometry */ + unsigned label_spacing; + /** distance the label can be moved on the line to fit, if 0 the default is used */ + unsigned label_position_tolerance; bool avoid_edges; double minimum_distance; double minimum_padding; double minimum_path_length; double max_char_angle_delta; - bool force_odd_labels; //Always try render an odd amount of labels + /** Always try render an odd amount of labels */ + bool force_odd_labels; bool allow_overlap; unsigned text_ratio; unsigned wrap_width; - text_processor processor; //Contains expressions and text formats + /** Contains everything related to text formating */ + text_processor processor; }; + +/** Generate a possible placement and store results of placement_finder. + * This placement has first to be tested by placement_finder to verify it + * can actually be used. + */ class text_placement_info : boost::noncopyable { public: + /** Constructor. Takes the parent text_placements object as a parameter + * to read defaults from it. */ text_placement_info(text_placements const* parent); /** Get next placement. * This function is also called before the first placement is tried. * Each class has to return at least one position! - * If this functions returns false the placement data should be considered invalid! + * If this functions returns false the placement data should be + * considered invalid! */ virtual bool next()=0; virtual ~text_placement_info() {} + /** Initialize values used by placement finder. Only has to be done once + * per object. + */ void init(double scale_factor_, unsigned w = 0, unsigned h = 0, bool has_dimensions_ = false); + /** Properties actually used by placement finder and renderer. Values in + * here are modified each time next() is called. */ text_symbolizer_properties properties; + + /** Scale factor used by the renderer. */ double scale_factor; + /* TODO: Don't know what this is used for. */ bool has_dimensions; + /* TODO: Don't know what this is used for. */ std::pair dimensions; + /** Set scale factor. */ void set_scale_factor(double factor) { scale_factor = factor; } + /** Get scale factor. */ double get_scale_factor() { return scale_factor; } + /** Get label spacing taking the scale factor into account. */ double get_actual_label_spacing() { return scale_factor * properties.label_spacing; } + /** Get minimum distance taking the scale factor into account. */ double get_actual_minimum_distance() { return scale_factor * properties.minimum_distance; } + /** Get minimum padding taking the scale factor into account. */ double get_actual_minimum_padding() { return scale_factor * properties.minimum_padding; } + /** Collect a bounding box of all texts placed. */ bool collect_extents; - //Output + //Output by placement finder + /** Bounding box of all texts placed. */ box2d extents; + /* TODO */ std::queue< box2d > envelopes; + /* TODO */ boost::ptr_vector placements; }; typedef boost::shared_ptr text_placement_info_ptr; +/** This object handles the management of all TextSymbolizer properties. It can + * be used as a base class for own objects which implement new processing + * semantics. Basically this class just makes sure a pointer of the right + * class is returned by the get_placement_info call. + */ class text_placements { public: text_placements(); + /** Get a text_placement_info object to use in rendering. + * The returned object creates a list of settings which is + * used to try to find a placement and stores all + * information that is generated by + * the placement finder. + * + * This function usually is implemented as + * text_placement_info_ptr text_placements_XXX::get_placement_info() const + * { + * return text_placement_info_ptr(new text_placement_info_XXX(this)); + * } + */ virtual text_placement_info_ptr get_placement_info() const =0; /** Get a list of all expressions used in any placement. * This function is used to collect attributes. */ virtual std::set get_all_expressions(); + /** Destructor. */ virtual ~text_placements() {} + + /** List of all properties used as the default for the subclasses. */ text_symbolizer_properties properties; }; +/** Pointer to object of class text_placements */ typedef boost::shared_ptr text_placements_ptr; + class text_placements_info_dummy; +/** Dummy placement algorithm. Always takes the default value. */ class MAPNIK_DECL text_placements_dummy: public text_placements { public: @@ -177,6 +233,7 @@ public: friend class text_placement_info_dummy; }; +/** Placement info object for dummy placement algorithm. Always takes the default value. */ class MAPNIK_DECL text_placement_info_dummy : public text_placement_info { public: diff --git a/include/mapnik/text_processing.hpp b/include/mapnik/text_processing.hpp index ab111dc1b..512282b00 100644 --- a/include/mapnik/text_processing.hpp +++ b/include/mapnik/text_processing.hpp @@ -68,9 +68,6 @@ struct char_properties double halo_radius; }; -class abstract_token; -class processed_text; - class processed_expression { public: @@ -78,8 +75,7 @@ public: p(properties), str(text) {} char_properties p; UnicodeString str; -private: - friend class processed_text; + }; class processed_text @@ -101,15 +97,24 @@ private: string_info info_; }; +class abstract_token; +/** Stores formating information and uses this to produce formated text for a given feature. */ class text_processor { public: text_processor(); + /** Construct object from XML. */ void from_xml(boost::property_tree::ptree const& pt, std::map const &fontsets); + /** Write object to XML ptree. */ void to_xml(boost::property_tree::ptree &node, bool explicit_defaults, text_processor const& dfl) const; + + /** Takes a feature and produces formated text as output. + * The output object has to be created by the caller and passed in for thread safety. + */ void process(processed_text &output, Feature const& feature); void set_old_style_expression(expression_ptr expr); + /** Add a new formating token. */ void push_back(abstract_token *token); std::set get_all_expressions() const; char_properties defaults;