git_clone/thorvg
1
0
Fork 0
mirror of https://github.com/thorvg/thorvg.git synced 2025-06-14 12:04:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

doc: linguistic changes in C++ API docs

Browse source
This commit is contained in:
Mira Grudzinska 2021-05-02 23:04:54 +02:00 • committed by Hermet Park
parent 824b56acc1
commit dc637d0beb
1 changed files with 174 additions and 164 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

338
inc/thorvg.h
View file

@ -1,6 +1,14 @@
/*!
* @file thorvg.h
*/
* @file thorvg.h
*
* The main APIs enabling the TVG initialization, preparation of the canvas and provisioning of its content:
* - drawing shapes such as line, curve, arc, rectangle, circle or user-defined
* - drawing pictures - SVG, PNG, RAW
* - solid or gradient filling
* - continuous and dashed stroking
* - clipping and masking
* and finally drawing the canvas and TVG termination.
*/
#ifndef _THORVG_H_
@ -50,7 +58,8 @@ class Picture;
class Canvas;
/**
* @defgroup ThorVG
* @defgroup ThorVG ThorVG
* @brief ThorVG classes and enumerations providing C++ APIs.
*/
/**@{*/
@ -60,7 +69,7 @@ class Canvas;
*/
enum class TVG_EXPORT Result
{
Success = 0, ///< The value returned in case of the correct request execution.
Success = 0, ///< The value returned in case of a correct request execution.
InvalidArguments, ///< The value returned in the event of a problem with the arguments given to the API - e.g. empty paths or null pointers.
InsufficientCondition, ///< The value returned in case the request cannot be processed - e.g. asking for properties of an object, which does not exist.
FailedAllocation, ///< The value returned in case of unsuccessful memory allocation.
@ -77,10 +86,10 @@ enum class TVG_EXPORT Result
*/
enum class TVG_EXPORT PathCommand
{
Close = 0, ///< Ends the current sub-path and connects it with its initial point. This command expects 1 point: close position.
MoveTo, ///< Sets a new initial point of the sub-path and a new current point. This command expects 1 point: moving position.
LineTo, ///< Draws a line from the current point to the given point and sets a new value of the current point. This command expects 1 point: end position of the line.
CubicTo ///< Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point. This command expects 3 points: control 1, control 2, end.
Close = 0, ///< Ends the current sub-path and connects it with its initial point. This command doesn't expect any points.
MoveTo, ///< Sets a new initial point of the sub-path and a new current point. This command expects 1 point: the starting position.
LineTo, ///< Draws a line from the current point to the given point and sets a new value of the current point. This command expects 1 point: the end-position of the line.
CubicTo ///< Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point. This command expects 3 points: the 1st control-point, the 2nd control-point, the end-point of the curve.
};
/**
@ -134,7 +143,7 @@ enum class TVG_EXPORT CompositeMethod
};
/**
* @brief Enumeration specifying the engine type used for the graphics backend. For multiple backeneds, Bitwise operation is allowed.
* @brief Enumeration specifying the engine type used for the graphics backend. For multiple backeneds bitwise operation is allowed.
*/
enum class TVG_EXPORT CanvasEngine
{
@ -170,12 +179,11 @@ struct Matrix
/**
* @class Paint
*
* @brief A abstract class for managing graphical elements.
*
* Basically a graphical elements in TVG is composed as an object in a scene (Canvas).
* Paint represents a graphical object, suggest common behaviors such as duplication, transformation and composition, etc.
* TVG recommends user to regard a paint as a pack of volatile commands, they can prepare a paint then request Canvas to run it.
* @brief An abstract class for managing graphical elements.
*
* A graphical element in TVG is any object composed into a Canvas.
* Paint represents such a graphical object and its behaviors such as duplication, transformation and composition.
* TVG recommends the user to regard a paint as a set of volatile commands. They can prepare a Paint and then request a Canvas to run them.
*/
class TVG_EXPORT Paint
{
@ -183,23 +191,23 @@ public:
virtual ~Paint();
/**
* @brief Sets the angle by which object is rotated.
* @brief Sets the angle by which the object is rotated.
*
* The angle in measured clockwise from the horizontal axis.
* The rotational axis passes through the point on the object with zero coordinates.
*
* @param[in] degree The value of the angle in degrees.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result rotate(float degree) noexcept;
/**
* @brief Sets the scale value of the object.
*
* @param[in] factor The value of the scaling factor. Default value is 1.
* @param[in] factor The value of the scaling factor. The default value is 1.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result scale(float factor) noexcept;
@ -207,12 +215,12 @@ public:
* @brief Sets the values by which the object is moved in a two-dimensional space.
*
* The origin of the coordinate system is in the upper left corner of the canvas.
* The horizontal and vertical axes points to the right and down, respectively.
* The horizontal and vertical axes point to the right and down, respectively.
*
* @param[in] x The value of the horizontal shift.
* @param[in] y The value of the vertical shift.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result translate(float x, float y) noexcept;
@ -223,7 +231,7 @@ public:
*
* @param[in] m The 3x3 augmented matrix.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*
*/
Result transform(const Matrix& m) noexcept;
@ -233,19 +241,19 @@ public:
*
* @param[in] o The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
*
* @return @c Result::Success.
* @return Result::Success when succeed.
*
* @note A half-translucent paint by opacity may require multiple render pass for composition, TVG recommends to avoid opacity change as possible.
* @note Setting the opacity with this API may require multiple render pass for composition. It is recommended to avoid changing the opacity if possible.
*/
Result opacity(uint8_t o) noexcept;
/**
* @brief Sets the composition target object and the composition method.
*
* @param[in] target The paint to the target object.
* @param[in] target The paint of the target object.
* @param[in] method The method used to composite the source object with the target.
*
* @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise.
* @return Result::Success when succeed, Result::InvalidArguments otherwise.
*
*/
Result composite(std::unique_ptr<Paint> target, CompositeMethod method) const noexcept;
@ -258,16 +266,16 @@ public:
* @param[out] w The width of the object.
* @param[out] h The height of the object.
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
*
* @note bounding box doesn't indicate the rendering region in the result but primitive region of the object.
* @note The bounding box doesn't indicate the final rendered region. It's the smallest rectangle that encloses the object.
*/
Result bounds(float* x, float* y, float* w, float* h) const noexcept;
/**
* @brief Duplicates the object.
*
* Creates a new object and sets all properties as in the original object.
* Creates a new object and sets its all properties as in the original object.
*
* @return The created object when succeed, @c nullptr otherwise.
*/
@ -288,7 +296,7 @@ public:
/**
* @class Fill
*
* @brief A abstract class representing the gradient fill of the Shape object.
* @brief An abstract class representing the gradient fill of the Shape object.
*
* It contains the information about the gradient colors and their arrangement
* inside the gradient bounds. The gradients bounds are defined in the LinearGradient
@ -319,7 +327,7 @@ public:
* @param[in] colorStops An array of ColorStop data structure.
* @param[in] cnt The count of the @p colorStops array equal to the colors number used in the gradient.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result colorStops(const ColorStop* colorStops, uint32_t cnt) noexcept;
@ -328,7 +336,7 @@ public:
*
* @param[in] s The FillSpread value.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result spread(FillSpread s) noexcept;
@ -365,12 +373,12 @@ public:
/**
* @class Canvas
*
* @brief A abstract class for drawing graphical elements.
* @brief An abstract class for drawing graphical elements.
*
* A canvas is a unit to a drawing target. It sets up drawing engine and buffer, which can be drawn on the screen, it also manages given Paint objects.
* A canvas is an entity responsible for drawing the target. It sets up the drawing engine and the buffer, which can be drawn on the screen. It also manages given Paint objects.
*
* @note Canvas behavior depends on the raster engine though its drawing result is expected to be identical.
* @warning Paints are belongs to a Canvas, they can't be shared among multiple Canvases.
* @note A Canvas behavior depends on the raster engine though the final content of the buffer is expected to be identical.
* @warning The Paint objects belonging to one Canvas can't be shared among multiple Canvases.
*/
class TVG_EXPORT Canvas
{
@ -379,14 +387,14 @@ public:
virtual ~Canvas();
/**
* @brief Sets the size of the container, where all the paints pushed into the scene are stored.
* @brief Sets the size of the container, where all the paints pushed into the Canvas are stored.
*
* If the number of objects pushed into the Canvas is known in advance, calling the function
* prevents multiple memory reallocation, thus improving the performance.
*
* @param[in] n The number of objects for which the memory is to be reserved.
*
* @return Result::Success.
* @return Result::Success when succeed.
*/
Result reserve(uint32_t n) noexcept;
@ -395,15 +403,15 @@ public:
*
* Only pushed paints in the canvas will be drawing targets.
* They are retained by the canvas until you call Canvas::clear().
* If you know the count of push() in the advance, please call reserve().
* If you know the number of the pushed objects in the advance, please call Canvas::reserve().
*
* @param[in] paint A Paint object to be drawn.
*
* @retval @c Result::Success when succeed.
* @retval @c Result::MemoryCorruption In case a @c nullptr is passed as the argument.
* @retval @c Result::InsufficientCondition An internal error.
* @retval Result::Success When succeed.
* @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument.
* @retval Result::InsufficientCondition An internal error.
*
* @note Rendering order of the paints are in the order of the push. Thus if you mind a layering, sorting the paints before pushing them.
* @note The rendering order of the paints is the same as the order as they were pushed into the canvas. Consider sorting the paints before pushing them if you intend to use layering.
* @see Canvas::reserve()
* @see Canvas::clear()
*/
@ -411,35 +419,36 @@ public:
/**
* @brief Sets the total number of the paints pushed into the canvas to be zero.
* Depending on the value of the given argument @p free, the Paints were free or not.
* Depending on the value of the @p free argument, the paints are freed or not.
*
* @param[in] free If @c then true the memory occupied by paints is deallocated, otherwise it is not.
* @param[in] free If @c true, the memory occupied by paints is deallocated, otherwise it is not.
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
*
* @warning If you don't free the paints, they are totally dangled, they are supposed to be reused otherwise you are responsible for their lives. Thus please use that @p free option when you know how it works, otherwise it's not recommended.
* @warning If you don't free the paints they become dangled. They are supposed to be reused, otherwise you are responsible for their lives. Thus please use the @p free argument only when you know how it works, otherwise it's not recommended.
*/
virtual Result clear(bool free = true) noexcept;
/**
* @brief Request the canvas to update the paint objects.
*
* If a @c nullptr is passed all paint objects retained by the Canvas are updated, otherwise only the paint to which the given @p paint.
* If a @c nullptr is passed all paint objects retained by the Canvas are updated,
* otherwise only the paint to which the given @p paint points.
*
* @param[in] paint A pointer to the Paint object or @c nullptr.
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
*
* @note Updation behavior could be asynchronous by thread option.
* @note The Update behavior can be asynchronous if the assigned thread number is greater than zero.
*/
virtual Result update(Paint* paint) noexcept;
/**
* @brief Request the canvas to draw paint objects.
* @brief Request the canvas to draw the Paint objects.
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
*
* @note Drawing could be asynchronous by thread option. To guarantee the done of drawing job, call sync().
* @note Drawing can be asynchronous if the assigned thread number is greater than zero. To guarantee the drawing is done, call sync() afterwards.
* @see Canvas::sync()
*/
virtual Result draw() noexcept;
@ -447,11 +456,10 @@ public:
/**
* @brief Guarantees that drawing task is finished.
*
* The Canvas rendering can be performed asynchronously. To make sure that rendering is finished,
* The Canvas rendering can be performed asynchronously. To make sure that rendering is finished,
* the sync() should be called after the draw().
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
*
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
* @see Canvas::draw()
*/
virtual Result sync() noexcept;
@ -477,15 +485,15 @@ public:
* @brief Sets the linear gradient bounds.
*
* The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing
* the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking
* (x1, y1) and (x2, y2).
* the given points (@p x1, @p y1) and (@p x2, @p y2), respectively. Both lines are perpendicular to the line linking
* (@p x1, @p y1) and (@p x2, @p y2).
*
* @param[in] x1 The horizontal coordinate of the first point used to determine the gradient bounds.
* @param[in] y1 The vertical coordinate of the first point used to determine the gradient bounds.
* @param[in] x2 The horizontal coordinate of the second point used to determine the gradient bounds.
* @param[in] y2 The vertical coordinate of the second point used to determine the gradient bounds.
*
* @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise.
* @return Result::Success when succeed, Result::InvalidArguments otherwise.
*/
Result linear(float x1, float y1, float x2, float y2) noexcept;
@ -493,15 +501,15 @@ public:
* @brief Gets the linear gradient bounds.
*
* The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing
* the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking
* (x1, y1) and (x2, y2).
* the given points (@p x1, @p y1) and (@p x2, @p y2), respectively. Both lines are perpendicular to the line linking
* (@p x1, @p y1) and (@p x2, @p y2).
*
* @param[out] x1 The horizontal coordinate of the first point used to determine the gradient bounds.
* @param[out] y1 The vertical coordinate of the first point used to determine the gradient bounds.
* @param[out] x2 The horizontal coordinate of the second point used to determine the gradient bounds.
* @param[out] y2 The vertical coordinate of the second point used to determine the gradient bounds.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result linear(float* x1, float* y1, float* x2, float* y2) const noexcept;
@ -530,26 +538,26 @@ public:
/**
* @brief Sets the radial gradient bounds.
*
* The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius.
* The radial gradient bounds are defined as a circle centered in a given point (@p cx, @p cy) of a given radius.
*
* @param[in] cx The horizontal coordinate of the center of the bounding circle.
* @param[in] cy The vertical coordinate of the center of the bounding circle.
* @param[in] radius The radius of the bounding circle.
*
* @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise.
* @return Result::Success when succeed, Result::InvalidArguments otherwise.
*/
Result radial(float cx, float cy, float radius) noexcept;
/**
* @brief Gets the radial gradient bounds.
*
* The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius.
* The radial gradient bounds are defined as a circle centered in a given point (@p cx, @p cy) of a given radius.
*
* @param[out] cx The horizontal coordinate of the center of the bounding circle.
* @param[out] cy The vertical coordinate of the center of the bounding circle.
* @param[out] radius The radius of the bounding circle.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result radial(float* cx, float* cy, float* radius) const noexcept;
@ -569,11 +577,11 @@ public:
*
* @brief A class representing two-dimensional figures and their properties.
*
* A shape is consisted of major 3 properties: shape outline, stroking, filling. The outline in the Shape is retained as the pathe.
* Path can be composed by accumulating primitive commands such as moveTo(), lineTo(), curbicTo(), or complete shape interfaces such as appendRect(), appendCircle(), etc.
* Path could be consisten of sub-pathes, one sub-path is determined by close commoand.
* A shape has three major properties: shape outline, stroking, filling. The outline in the Shape is retained as the path.
* Path can be composed by accumulating primitive commands such as moveTo(), lineTo(), cubicTo(), or complete shape interfaces such as appendRect(), appendCircle(), etc.
* Path can consists of sub-paths. One sub-path is determined by a close command.
*
* Stroke of Shape is an optional property in a certain case if the shape needs to be represented with/without outline borders.
* The stroke of Shape is an optional property in case the Shape needs to be represented with/without the outline borders.
* It's efficient since the shape path and the stroking path can be shared with each other. It's also convenient when controlling both in one context.
*/
class TVG_EXPORT Shape final : public Paint
@ -582,11 +590,11 @@ public:
~Shape();
/**
* @brief Resets the properties of shape path.
* @brief Resets the properties of the shape path.
*
* The properties of the color, fill and the stroke is kept.
* The color, the fill and the stroke properties are retained.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*
* @note The memory, where the path data is stored, is not deallocated at this stage for caching effect.
*/
@ -600,7 +608,7 @@ public:
* @param[in] x The horizontal coordinate of the initial point of the sub-path.
* @param[in] y The vertical coordinate of the initial point of the sub-path.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result moveTo(float x, float y) noexcept;
@ -609,12 +617,12 @@ public:
*
* The value of the current point is set to the given end-point.
*
* @param[in] x The horizontal coordinate of the endpoint of the line.
* @param[in] y The vertical coordinate of the endpoint of the line.
* @param[in] x The horizontal coordinate of the end-point of the line.
* @param[in] y The vertical coordinate of the end-point of the line.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*
* @note In case this is the first command in the path, it corresponds to the moveTo command.
* @note In case this is the first command in the path, it corresponds to the moveTo() call.
*/
Result lineTo(float x, float y) noexcept;
@ -628,10 +636,10 @@ public:
* @param[in] cy1 The vertical coordinate of the 1st control point.
* @param[in] cx2 The horizontal coordinate of the 2nd control point.
* @param[in] cy2 The vertical coordinate of the 2nd control point.
* @param[in] x The horizontal coordinate of the endpoint of the curve.
* @param[in] y The vertical coordinate of the endpoint of the curve.
* @param[in] x The horizontal coordinate of the end-point of the curve.
* @param[in] y The vertical coordinate of the end-point of the curve.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*
* @note In case this is the first command in the path, no data from the path are rendered.
*/
@ -642,7 +650,7 @@ public:
*
* The value of the current point is set to the initial point of the closed sub-path.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*
* @note In case the sub-path does not contain any points, this function has no effect.
*/
@ -652,8 +660,7 @@ public:
* @brief Appends a rectangle to the path.
*
* The rectangle with rounded corners can be achieved by setting non-zero values to @p rx and @p ry arguments.
* The @p rx and @p ry values specify the radius of the ellipse defining the rounding of the corners.
* For the @p rx and @p ry values less than the half of the width and the half of the height of respectively, an ellipse is drawn.
* The @p rx and @p ry values specify the radii of the ellipse defining the rounding of the corners.
*
* The position of the rectangle is specified by the coordinates of its upper left corner - @p x and @p y arguments.
*
@ -669,9 +676,9 @@ public:
* @param[in] rx The x-axis radius of the ellipse defining the rounded corners of the rectangle.
* @param[in] ry The y-axis radius of the ellipse defining the rounded corners of the rectangle.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*
* @note if @p rx and @p ry is greater than half of @p w and half of @p h, the shape becomes to a circle.
* @note For @p rx and @p ry greater than or equal to the half of @p w and the half of @p h, respectively, the shape become an ellipse.
*/
Result appendRect(float x, float y, float w, float h, float rx, float ry) noexcept;
@ -689,7 +696,7 @@ public:
* @param[in] rx The x-axis radius of the ellipse.
* @param[in] ry The y-axis radius of the ellipse.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result appendCircle(float cx, float cy, float rx, float ry) noexcept;
@ -697,17 +704,17 @@ public:
* @brief Appends a circular arc to the path.
*
* The arc is treated as a new sub-path - it is not connected with the previous sub-path.
* The current point value is set to the end-point of the arc in case @p pie is @c false and to the center of the arc otherwise.
* The current point value is set to the end-point of the arc in case @p pie is @c false, and to the center of the arc otherwise.
*
* @param[in] cx The horizontal coordinate of the center of the arc.
* @param[in] cy The vertical coordinate of the center of the arc.
* @param[in] radius The radius of the arc.
* @param[in] startAngle The start angle of the arc given in degrees, measured counter clockwise from the horizontal line.
* @param[in] sweep The central angle of the arc given in degrees, measured counter clock-wise from @p startAngle.
* @param[in] pie Specifies whether to draw radius from the arc's center to both of its end-point - drawn if @c true.
* @param[in] startAngle The start angle of the arc given in degrees, measured counter-clockwise from the horizontal line.
* @param[in] sweep The central angle of the arc given in degrees, measured counter-clockwise from @p startAngle.
* @param[in] pie Specifies whether to draw radii from the arc's center to both of its end-point - drawn if @c true.
*
* @return Result::Success when succeed.
*
* @return @c Result::Success when succeed.
*
* @note Setting @p sweep value greater than 360 degrees, is equivalent to calling appendCircle(cx, cy, radius, radius).
*/
Result appendArc(float cx, float cy, float radius, float startAngle, float sweep, bool pie) noexcept;
@ -723,9 +730,9 @@ public:
* @param[in] pts The array of the two-dimensional points.
* @param[in] ptsCnt The number of the points in the @p pts array.
*
* @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise.
* @return Result::Success when succeed, Result::InvalidArguments otherwise.
*
* @note This interface is designed for optimal path setting if the caller has a completed path commands already.
* @note The interface is designed for optimal path setting if the caller has a completed path commands already.
*/
Result appendPath(const PathCommand* cmds, uint32_t cmdCnt, const Point* pts, uint32_t ptsCnt) noexcept;
@ -734,7 +741,7 @@ public:
*
* @param[in] width The width of the stroke. The default value is 0.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result stroke(float width) noexcept;
@ -746,18 +753,18 @@ public:
* @param[in] b The blue color channel value in the range [0 ~ 255]. The default value is 0.
* @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
/**
* @brief Sets the gradient fill of the stroke for all of the figures from the path..
* @brief Sets the gradient fill of the stroke for all of the figures from the path.
*
* @param[in] The gradient fill.
* @param[in] f The gradient fill.
*
* @retval @c Result::Success When succeed.
* @retval @c Result::FailedAllocation An internal error with a memory allocation for an object to be filled.
* @retval @c Result::MemoryCorruption In case a @c nullptr is passed as the argument.
* @retval Result::Success When succeed.
* @retval Result::FailedAllocation An internal error with a memory allocation for an object to be filled.
* @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument.
*/
Result stroke(std::unique_ptr<Fill> f) noexcept;
@ -765,11 +772,11 @@ public:
* @brief Sets the dash pattern of the stroke.
*
* @param[in] dashPattern The array of consecutive pair values of the dash length and the gap length.
* @param[in] cnt The length of @p dashPattern array.
* @param[in] cnt The length of the @p dashPattern array.
*
* @retval @c Result::Success when succeed.
* @retval @c Result::FailedAllocation An internal error with a memory allocation for an object to be dashed.
* @retval @c Result::InvalidArguments In case a @c nullptr is passed as the @p dashPattern,
* @retval Result::Success When succeed.
* @retval Result::FailedAllocation An internal error with a memory allocation for an object to be dashed.
* @retval Result::InvalidArguments In case a @c nullptr is passed as the @p dashPattern,
* the given length of the array is less than two or any of the @p dashPattern values is zero or less.
*
* @note If any of the dash pattern values is zero, this function has no effect.
@ -781,18 +788,18 @@ public:
*
* @param[in] cap The cap style value. The default value is @c StrokeCap::Square.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result stroke(StrokeCap cap) noexcept;
/**
* @brief Sets the join style for stroked path segments.
*
* The join style will be used for joining the two line segment while stroking the path.
* The join style is used for joining the two line segment while stroking the path.
*
* @param[in] join The join style value. The default value is @c StrokeJoin::Bevel.
*
* @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise.
* @return Result::Success when succeed, Result::FailedAllocation otherwise.
*/
Result stroke(StrokeJoin join) noexcept;
@ -806,9 +813,9 @@ public:
* @param[in] b The blue color channel value in the range [0 ~ 255]. The default value is 0.
* @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*
* @note Either solid color or gradient fill which is lastly set will be applied.
* @note Either a solid color or a gradient fill is applied, depending on what was set as last.
*/
Result fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
@ -819,9 +826,9 @@ public:
*
* @param[in] f The unique pointer to the gradient fill.
*
* @return @c Result::Success when succeed, @c Result::MemoryCorruption otherwise.
* @return Result::Success when succeed, Result::MemoryCorruption otherwise.
*
* @note Either solid color or gradient fill which is lastly set will be applied.
* @note Either a solid color or a gradient fill is applied, depending on what was set as last.
*/
Result fill(std::unique_ptr<Fill> f) noexcept;
@ -830,7 +837,7 @@ public:
*
* @param[in] r The fill rule value.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result fill(FillRule r) noexcept;
@ -867,7 +874,7 @@ public:
* @param[out] b The blue color channel value in the range [0 ~ 255].
* @param[out] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result fillColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const noexcept;
@ -893,7 +900,7 @@ public:
* @param[out] b The blue color channel value in the range [0 ~ 255].
* @param[out] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
*/
Result strokeColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const noexcept;
@ -909,7 +916,7 @@ public:
*
* @param[out] dashPattern The pointer to the memory, where the dash pattern array is stored.
*
* @return The length of dash pattern array.
* @return The length of the @p dashPattern array.
*/
uint32_t strokeDash(const float** dashPattern) const noexcept;
@ -942,7 +949,7 @@ public:
* @class Picture
*
* @brief A class representing an image read in one of the supported formats: raw, svg, png and etc.
* Besides the methods inherited from the Paint, it provides eaiser methods to load & draw images on the canvas.
* Besides the methods inherited from the Paint, it provides methods to load & draw images on the canvas.
*
* @note Supported formats are depended on the available TVG loaders.
*/
@ -952,16 +959,17 @@ public:
~Picture();
/**
* @brief Loads a picture data from a file directly.
* @brief Loads a picture data directly from a file.
*
* @param[in] path A path to the picture file.
*
* @retval @c Result::Success when succeed.
* @retval @c Result::InvalidArguments In case the @p path is empty.
* @retval @c Result::NonSupport When trying to load a file with an unknown extension.
* @retval @c Result::Unknown If an error occurs at a later stage.
* @retval Result::Success When succeed.
* @retval Result::InvalidArguments In case the @p path is empty.
* @retval Result::NonSupport When trying to load a file with an unknown extension.
* @retval Result::Unknown If an error occurs at a later stage.
*
* @note loading behavior could be asynchronous by thread option.
* @note The Load behavior can be asynchronous if the assigned thread number is greater than zero.
* @see Initializer::init()
*/
Result load(const std::string& path) noexcept;
@ -971,10 +979,10 @@ public:
* @param[in] data A pointer to a memory location where the content of the picture file is stored.
* @param[in] size The size in bytes of the memory occupied by the @p data.
*
* @retval @c Result::Success when succeed.
* @retval @c Result::InvalidArguments In case no data are provided or the @p size is zero or less.
* @retval @c Result::NonSupport When trying to load a file with an unknown extension.
* @retval @c Result::Unknown If an error occurs at a later stage.
* @retval Result::Success When succeed.
* @retval Result::InvalidArguments In case no data are provided or the @p size is zero or less.
* @retval Result::NonSupport When trying to load a file with an unknown extension.
* @retval Result::Unknown If an error occurs at a later stage.
*
* @note: This api supports only SVG format
*/
@ -989,16 +997,17 @@ public:
* @param[in] w A new width of the image in pixels.
* @param[in] h A new height of the image in pixels.
*
* @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise.
* @return Result::Success when succeed, Result::InsufficientCondition otherwise.
*/
Result size(float w, float h) noexcept;
/**
* @brief Gets the size of the image.
*
* @param[out] w The width of the image in pixels.
* @param[out] h The height of the image in pixels.
*
* @return @c Result::Success when succeed.
* @return Result::Success when succeed.
*/
Result size(float* w, float* h) const noexcept;
@ -1039,10 +1048,10 @@ public:
*
* @brief A class to composite children paints.
*
* As the traditional graphics rendering method, TVG also enables scene-graph mechanism,
* As the traditional graphics rendering method, TVG also enables scene-graph mechanism.
* This feature supports an array function for managing the multiple paints as one group paint.
*
* As a group, scene can be transformed, translucent, composited with other target paints,
* As a group, the scene can be transformed, made translucent and composited with other target paints,
* its children will be affected by the scene world.
*/
class TVG_EXPORT Scene final : public Paint
@ -1055,25 +1064,26 @@ public:
*
* Only pushed paints in the scene will be drawing targets.
* They are retained by the scene until you call Scene::clear().
* If you know the count of push() in the advance, please call Scene::reserve().
* If you know the number of the pushed objects in the advance, please call Scene::reserve().
*
* @param[in] paint A Paint object to be drawn.
*
* @return @c Result::Success when succeed, @c Result::MemoryCorruption otherwise.
* @return Result::Success when succeed, Result::MemoryCorruption otherwise.
*
* @note Rendering order of the paints are in the order of the push. Thus if you mind a layering, sorting the paints before pushing them.
* @note The rendering order of the paints is the same as the order as they were pushed. Consider sorting the paints before pushing them if you intend to use layering.
* @see Scene::reserve()
*/
Result push(std::unique_ptr<Paint> paint) noexcept;
/**
* @brief Sets the size of the container, where all the paints pushed into the scene are stored.
* @brief Sets the size of the container, where all the paints pushed into the Scene are stored.
*
* If the number of objects pushed into the scene is known in advance, calling the function
* prevents multiple memory reallocation, thus improving the performance.
*
* @param[in] size The number of objects for which the memory is to be reserved.
*
* @return @c Result::Success.
* @return Result::Success when succeed.
*/
Result reserve(uint32_t size) noexcept;
@ -1098,7 +1108,7 @@ public:
/**
* @class SwCanvas
*
* @brief A class for the rendering graphic elements with a software raster engine.
* @brief A class for the rendering graphical elements with a software raster engine.
*/
class TVG_EXPORT SwCanvas final : public Canvas
{
@ -1131,18 +1141,18 @@ public:
*
* The buffer of a desirable size should be allocated and owned by the caller.
*
* @param[in] buffer A pointer to a memory block of the size @p w x @p h, where the raster data are stored.
* @param[in] buffer A pointer to a memory block of the size @p stride x @p h, where the raster data are stored.
* @param[in] stride The stride of the raster image - greater than or equal to @p w.
* @param[in] w The width of the raster image.
* @param[in] h The height of the raster image.
* @param[in] cs The value specifying the way the 32-bits colors should be read/written.
*
* @retval @c Result::Success when succeed.
* @retval @c Result::MemoryCorruption When casting in the internal function implementation failed.
* @retval @c Result::InvalidArguments In case no valid pointer is provided or the width, or the height or the stride is zero.
* @retval @c Result::NonSupport In case the software engine is not supported.
* @retval Result::Success When succeed.
* @retval Result::MemoryCorruption When casting in the internal function implementation failed.
* @retval Result::InvalidArguments In case no valid pointer is provided or the width, or the height or the stride is zero.
* @retval Result::NonSupport In case the software engine is not supported.
*
* @warning Do not access @p buffer during Canvas::draw() - Canvas::sync(). It should not be accessed while TVG is writing on it.
* @warning Do not access @p buffer during Canvas::draw() - Canvas::sync(). It should not be accessed while TVG is writing on it.
*/
Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept;
@ -1173,7 +1183,7 @@ public:
/**
* @brief Creates a new SwCanvas object.
* @return A new SwCanvas object when succeed, otherwise @c nullptr
* @return A new SwCanvas object.
*/
static std::unique_ptr<SwCanvas> gen() noexcept;
@ -1186,7 +1196,7 @@ public:
*
* @brief A class for the rendering graphic elements with a GL raster engine.
*
* @warning Please do not use it, This class is not fully supported yet.
* @warning Please do not use it. This class is not fully supported yet.
*/
class TVG_EXPORT GlCanvas final : public Canvas
{
@ -1203,7 +1213,7 @@ public:
/**
* @brief Creates a new GlCanvas object.(BETA version)
*
* @return A new GlCanvas object when succeed, otherwise @c nullptr
* @return A new GlCanvas object.
*/
static std::unique_ptr<GlCanvas> gen() noexcept;
@ -1223,20 +1233,20 @@ public:
* @brief Initializes TVG engines.
*
* TVG requires the running-engine environment.
* Basically TVG runs its own task-scheduler for parallelizing rendering tasks efficiently.
* For the benefits, you can indicates threads numbers which count is designated TVG threads.
* In the initialization step, TVG will generate/spawn the threads by @p threads count.
* TVG runs its own task-scheduler for parallelizing rendering tasks efficiently.
* You can indicate the number of threads, the count of which is designated @p threads.
* In the initialization step, TVG will generate/spawn the threads as set by @p threads count.
*
* @param[in] engine The engine types to initialize. This is relative to Canvas types which will be used in. For multiple backeneds, Bitwise operation is allowed
* @param[in] threads The number of additional threads. Zero indiciates the main thread.
* @param[in] engine The engine types to initialize. This is relative to the Canvas types, in which it will be used. For multiple backeneds bitwise operation is allowed.
* @param[in] threads The number of additional threads. Zero indicates only the main thread is to be used.
*
* @retval @c Result::Success when succeed.
* @retval @c Result::InsufficientCondition An internal error possibly with memory allocation.
* @retval @c Result::InvalidArguments If unknown engine type chosen.
* @retval @c Result::NonSupport In case the engine type is not supported on the system.
* @retval @c Result::Unknown Others.
* @retval Result::Success When succeed.
* @retval Result::InsufficientCondition An internal error possibly with memory allocation.
* @retval Result::InvalidArguments If unknown engine type chosen.
* @retval Result::NonSupport In case the engine type is not supported on the system.
* @retval Result::Unknown Others.
*
* @note Initialilzer does own reference counting for multiple calls. Threads count will be fixed at the first init() call.
* @note The Initializer keeps track of the number of times it was called. Threads count is fixed at the first init() call.
* @see Initializer::term()
*/
static Result init(CanvasEngine engine, uint32_t threads) noexcept;
@ -1244,15 +1254,15 @@ public:
/**
* @brief Terminates TVG engines.
*
* @param[in] engine The engine types to terminate. This is relative to Canvas types which will be used in. For multiple backeneds, Bitwise operation is allowed
* @param[in] engine The engine types to terminate. This is relative to the Canvas types, in which it will be used. For multiple backeneds bitwise operation is allowed
*
* @retval @c Result::Success when succeed.
* @retval @c Result::InsufficientCondition In case there is nothing to be terminated.
* @retval @c Result::InvalidArguments If unknown engine type chosen.
* @retval @c Result::NonSupportt In case the engine type is not supported on the system.
* @retval @c Result::Unknown Others.
* @retval Result::Success When succeed.
* @retval Result::InsufficientCondition In case there is nothing to be terminated.
* @retval Result::InvalidArguments If unknown engine type chosen.
* @retval Result::NonSupport In case the engine type is not supported on the system.
* @retval Result::Unknown Others.
*
* @note Initialilzer does own reference counting for multiple calls.
* @note Initializer does own reference counting for multiple calls.
* @see Initializer::init()
*/
static Result term(CanvasEngine engine) noexcept;