diff options
Diffstat (limited to 'src/3rdparty/2geom/src/2geom/doxygen.cpp')
| -rw-r--r-- | src/3rdparty/2geom/src/2geom/doxygen.cpp | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/src/3rdparty/2geom/src/2geom/doxygen.cpp b/src/3rdparty/2geom/src/2geom/doxygen.cpp new file mode 100644 index 0000000..3c64eec --- /dev/null +++ b/src/3rdparty/2geom/src/2geom/doxygen.cpp @@ -0,0 +1,301 @@ +/* + * Doxygen documentation for the lib2geom library + * + * Authors: + * Krzysztof Kosiński <tweenk.pl@gmail.com> + * + * Copyright 2009-2011 Authors + * + * This library is free software; you can redistribute it and/or + * modify it either under the terms of the GNU Lesser General Public + * License version 2.1 as published by the Free Software Foundation + * (the "LGPL") or, at your option, under the terms of the Mozilla + * Public License Version 1.1 (the "MPL"). If you do not alter this + * notice, a recipient may use your version of this file under either + * the MPL or the LGPL. + * + * You should have received a copy of the LGPL along with this library + * in the file COPYING-LGPL-2.1; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * You should have received a copy of the MPL along with this library + * in the file COPYING-MPL-1.1 + * + * The contents of this file are subject to the Mozilla Public License + * Version 1.1 (the "License"); you may not use this file except in + * compliance with the License. You may obtain a copy of the License at + * http://www.mozilla.org/MPL/ + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY + * OF ANY KIND, either express or implied. See the LGPL or the MPL for + * the specific language governing rights and limitations. + */ + +// Main page of the documentation - contains logo and introductory text +/** + * @mainpage + * + * @image html 2geom-logo.png + * + * @section Introduction + * + * 2Geom is a computational geometry library intended for use with 2D vector graphics. + * It concentrates on high-level algorithms, such as computing the length of a curve + * or Boolean operations on paths. It evolved from the geometry code used + * in Inkscape, a free software, cross-platform vector graphics editor. + * + * @section UserGuide User guide + * + * - @subpage Overview "Overview of 2Geom" + * - @ref Primitives "Primitives" - points, angles, lines, axis-aligned rectangles... + * - @ref Transforms "Transformations" - mathematical representation for operations + * like translation, scaling and rotation. + * - @ref Fragments "Fragments" - one-dimensional functions and related utilities. + * - @ref Curves "Curves" - functions mapping the unit interval to points on a plane. + * - @ref Shapes "Shapes" - circles, ellipses, polygons and the like. + * - @ref Paths "Paths" - sequences of contiguous curves, aka splines, and their processing. + * - @ref ShapeOps "Shape operations" - boolean algebra, offsets and other advanced operations. + * - @ref Containers "Geometric containers" - efficient ways to store and retrieve + * geometric information. + * - @ref Utilities "Utilities" - other useful code that does not fit under the above categories. + * - @subpage ReleaseNotes "Release notes" - what's new in 2Geom + * + * @section DeveloperInfo Developer information + * + * - @subpage CodingStandards "Coding standards used in 2Geom" + */ + +// Overview subpage +/** + * @page Overview Overview of 2Geom + * + * 2Geom has two APIs: a high level one, which uses virtual functions to allow handling + * objects of in a generic way without knowing their actual type at compile time, + * and a lower-level one based on templates, which is designed with performance in mind. + * For performance-critical tasks it may be necessary to use the lower level API. + * + * @section CoordSys Standard coordinate system + * + * 2Geom's standard coordinate system is common for computer graphics: the X axis grows + * to the right and the Y axis grows downwards. Angles start from the +X axis + * and grow towards the +Y axis (clockwise). + * + * @image html coords.png Standard coordinate system in 2Geom + * + * Most functions can be used without taking the coordinate system into account, + * as their interpretation is the same regardless of the coordinate system. However, + * a few of them depend on this definition, for example Rect's top() and bottom() methods. + * + * @section OpNote Operator note + * + * Most operators are provided by Boost operator helpers. This means that not all operators + * are defined in the class. For example, Rect only implements the operators + * +=, -= for points and *= for affines. The corresponding +, - and * operators + * are generated automatically by Boost. + */ + +// RELEASE NOTES +// Update this to describe the most important API changes. +/** + * @page ReleaseNotes 2Geom release notes + * + * @section Ver04 Version 0.4 + * - API additions: + * - Integer versions of Point, Interval and OptInterval, called + * IntPoint, IntInterval and OptIntInterval. + * - New geometric primitives: Angle and AngleInterval. + * - Major changes: + * - Matrix has been renamed to Affine. + * - Classification methods of Affine, for example Affine::isRotation(), will now + * return true for transforms that are close to identity. This is to reflect the + * fact that an identity transform can be interpreted as a rotation by zero + * degrees. To get the old behavior of returning false for identity, use + * methods prefixed with "Nonzero", e.g. Affine::isNonzeroRotation(). + * - EllipticalArc and SVGEllipticalArc have been merged. Now there is only the former. + * All arcs are SVG-compliant. + * - Minor changes: + * - Affine::without_translation() is now called Affine::withoutTranslation(). + * - Interval::strict_contains() is now called Interval::interiorContains(). + * The same change has been made for Rect. + * - Some unclear and unused operators of D2 were removed, for instance D2 * Point. + * - Interval is now a derived class of a GenericInterval template. + * - Rect is no longer a D2 specialization. + * - isnan.h merged with math-utils.h. + * @section Ver03 Version 0.3 + * - release notes were started after this version. + */ + +/** + * @page CodingStandards Coding standards and conventions used in 2Geom + * + * @section Filenames + * + * Files and directories should be all lowercase. Words should be separated with hyphens (-). + * Underscores, capital letters and non-ASCII characters should not be used. + * + * @section Indenting + * + * All files should use 4 spaces as indentation. + * + * @section Namespaces + * + * All classes intended for direct use by the end users should be in the Geom namespace. + * Contents of namespaces should not be indented. Closing brace of a namespace + * should have a comment indicating which namespace it is closing. + * @code + namespace Geom { + namespace FooInternal { + + unsigned some_function() + { + // ...code... + } + + } // namespace FooInternal + } // namespace Geom + @endcode + * + * @section Classes + * + * @code + // superclass list should use Boost notation, + // especially if there is more than one. + class Foo + : public Bar + , public Baz + { + // constructors should use Boost notation if the class has superclasses. + Foo(int a) + : Bar(a) + , Baz(b) + { + // constructor body + } + Foo(int a) { + // constructor with default initialization of superclasses + } + + // methods use camelCaseNames. + // one-line methods can be collapsed. + bool isActive() { return _blurp; } + // multi-line methods have the opening brace on the same line. + void invert() { + // ... code ... + } + + // static functions use lowercase_with_underscores. + // static factory functions should be called from_something. + static Foo from_point(Point const &p) { + // ... + } + }; // end of class Foo + + // Closing brace of a class should have the above comment, unless it's very short. + @endcode + * + * @section FreeFuns Free functions + * + * Functions should use lowercase_with_underscores names. The opening brace of + * the definition should be on a separate line. + * + * @section InlineInClasses When to use inline + * + * The "inline" keyword is not required when the body of the function is given + * in the definition of the class. Do not mark such functions inline, because + * they are automatically marked as inline by the compiler. It is only + * necessary to use the inline keyword when the body of the function is given + * after the class definition. + */ + +// Documentation for groups +/** + * @defgroup Transforms Affine transformations + * @brief Transformations of the plane such as rotation and scaling + * + * Each transformation class represent a set of affine transforms that is closed + * under multiplication. Those are translation, scaling, rotation, horizontal shearing + * and vertical shearing. Any affine transform can be obtained by combining those + * basic operations. + * + * Each of the transforms can be applied to points and matrices (using multiplication). + * Each can also be converted into a matrix (which can represent any composition + * of transforms generically). All (except translation) use the origin (0,0) as the invariant + * point (e.g. one that stays in the same place after applying the transform to the plane). + * To obtain transforms with different invariant points, combine them with translation to + * and back from the origin. For example, to get a 60 degree rotation around the point @a p: + * @code Affine rot_around_p = Translate(-p) * Rotate::from_degrees(60) * Translate(p); @endcode + * + * Multiplication of transforms is associative: the result of an expression involving + * points and matrices is the same regardless of the order of evaluating multiplications. + * + * If you need to transform a complicated object + * by A, then B, and then C, you should first compute the total transform and apply it to the + * object in one go. This way instead of performing 3 expensive operations, you will only do + * two very fast matrix multiplications and one complex transformation. Here is an example: + * @code + transformed_path = long_path * A * B * C; // wrong! long_path will be transformed 3 times. + transformed_path = long_path * (A * B * C); // good! long_path will be transformed only once. + Affine total = A * B * C; // you can store the transform to apply it to several objects. + transformed_path = long_path * total; // good! + @endcode + * Ordering note: if you compose transformations via multiplication, they are applied + * from left to right. If you write <code> ptrans = p * A * B * C * D;</code>, then it means + * that @a ptrans is obtained from @a p by first transforming it by A, then by B, then by C, + * and finally by D. This is a consequence of interpreting points as row vectors, instead + * of the more common column vector interpretation; 2Geom's choice leads to more intuitive + * notation. + */ + +/** + * @defgroup Primitives Primitives + * @brief Basic mathematical objects such as intervals and points + * + * 2Geom has several basic geometrical objects: points, lines, intervals, angles, + * and others. Most of those objects can be treated as sets of points or numbers + * satisfying some equation or as functions. + */ + +/** + * @defgroup Fragments Fragments and related classes + * @brief 1D functions on the unit interval + * + * Each type of fragments represents one of the various ways in which a function from + * the unit interval to the real line may be given. These are the most important mathematical + * primitives in 2Geom. + */ + +/** + * @defgroup Curves Curves + * @brief Functions mapping the unit interval to a plane + * + * Curves are functions \f$\mathbf{C}: [0, 1] \to \mathbb{R}^2\f$. For details, see + * the documentation for the Curve class. All curves can be included in paths and path sequences. + */ + +/** + * @defgroup Shapes Basic shapes + * @brief Circles, ellipes, polygons... + * + * Among the shapes supported by 2Geom are circles, ellipses and polygons. + * Polygons can also be represented by paths containing only linear segments. + */ + +/** + * @defgroup Paths Paths and path sequences + * @brief Sequences of contiguous curves, aka splines, and their processing + */ + +/** + * @defgroup Utilities Miscellaneous utilities + * @brief Useful code that does not fit under other categories. + */ + +/* + Local Variables: + mode:c++ + c-file-style:"stroustrup" + c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +)) + indent-tabs-mode:nil + fill-column:99 + End: +*/ +// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 : |