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

doc common: adding the documentation for the C++ APIs

Browse source 
Added the missing descriptions for Sw/Gl/Canvas and Initializer.
@retval command applied.
This commit is contained in:
Mira Grudzinska 2021-04-26 21:18:44 +02:00 • committed by Hermet Park
parent fa8b7b333e
commit 3d5006740c
1 changed files with 117 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

189
inc/thorvg.h
View file

@ -1,5 +1,5 @@
/*! /*!
* \file thorvg.h * @file thorvg.h
*/ */
@ -67,7 +67,8 @@ enum class TVG_EXPORT Result
/** /**
* @brief Enumeration specifying the values of the path commands accepted by ThorVG. * @brief Enumeration specifying the values of the path commands accepted by ThorVG.
* *
* Not to be confused with the path commands from the svg path element. * Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others).
* ThorVG interprets all of them and translates to the ones from the PathCommand values.
*/ */
enum class TVG_EXPORT PathCommand enum class TVG_EXPORT PathCommand
{ {
@ -162,7 +163,9 @@ struct Matrix
* *
* @ingroup ThorVG * @ingroup ThorVG
* *
* @brief A class for drawing a vector primitive. * @brief A class for managing graphic elements.
*
* It enables duplication, transformation and composition.
* *
*/ */
class TVG_EXPORT Paint class TVG_EXPORT Paint
@ -332,8 +335,9 @@ public:
* *
* @ingroup ThorVG * @ingroup ThorVG
* *
* @brief CanvasView is a class for displaying an vector primitives. * @brief A class for drawing graphic elements.
* *
* It stores all Paint objects (Shape, Scene, Picture) and creates the buffer, which can be drawn on the screen.
*/ */
class TVG_EXPORT Canvas class TVG_EXPORT Canvas
{ {
@ -341,35 +345,63 @@ public:
Canvas(RenderMethod*); Canvas(RenderMethod*);
virtual ~Canvas(); virtual ~Canvas();
Result reserve(uint32_t n) noexcept;
/** /**
* @brief Add paint object to the canvas * @brief Sets the size of the container, where all the paints pushed into the scene are stored.
* This method is similar to registration. The added paint is drawn on the inner canvas. *
* return * 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.
*/
Result reserve(uint32_t n) noexcept;
/**
* @brief Passes the Paint object to the Canvas.
*
* The function may be called many times and all passed objects will be rendered.
* Calling it initializes the data preparation of the chosen engine type.
*
* @param[in] paint A unique pointer to the Paint object.
* @retval Result::Success When succeeded.
* @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument.
* @retval Result::InsufficientCondition An internal error.
*/ */
virtual Result push(std::unique_ptr<Paint> paint) noexcept; virtual Result push(std::unique_ptr<Paint> paint) noexcept;
/** /**
* @brief * @brief Sets the total number of the paints pushed into the scene to be zero.
* @param[in] * Depending on the value of the given argument, the memory is free or not.
*
* @param[in] free If @c then true the memory occupied by paints is deallocated, otherwise it is not.
* return Result::Success when succeeded, Result::InsufficientCondition otherwise. * return Result::Success when succeeded, Result::InsufficientCondition otherwise.
*/ */
virtual Result clear(bool free = true) noexcept; virtual Result clear(bool free = true) noexcept;
/** /**
* @brief ... * @brief Updates the chosen Paint object or all objects from the Canvas object.
* @param[in] *
* return * If a @c nullptr is passed all objects from the Canvas are updated.
* Otherwise only the paint to which the given argument points.
*
* @param[in] paint A pointer to the Paint object or @c nullptr.
* return Result::Success when succeeded, Result::InsufficientCondition otherwise.
*/ */
virtual Result update(Paint* paint) noexcept; virtual Result update(Paint* paint) noexcept;
/** /**
* @brief Draw target buffer added to the canvas. * @brief Draws all objects from the Canvas object.
* return Result::Success when succeeded, Result::InsufficientCondition otherwise.
*/ */
virtual Result draw() noexcept; virtual Result draw() noexcept;
/** /**
* @brief ... * @brief Guaranties that all Paint objects from the Canvas object are already rendered.
*
* The Canvas components can be rendered asynchronously. To make sure, that all of them
* are ready, the sync API should be called after the draw API.
*
* return Result::Success when succeeded, Result::InsufficientCondition otherwise.
*/ */
virtual Result sync() noexcept; virtual Result sync() noexcept;
@ -481,7 +513,6 @@ public:
}; };
/** /**
* @class Shape * @class Shape
* *
@ -666,8 +697,10 @@ public:
/** /**
* @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] f The unique pointer to the gradient fill. * @param[in] The unique pointer to the gradient fill.
* @return Result::Success when succeeded, Result::FailedAllocation or Result::MemoryCorruption otherwise. * @retval Result::Success When succeeded.
* @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; Result stroke(std::unique_ptr<Fill> f) noexcept;
@ -678,7 +711,10 @@ public:
* *
* @param[in] dashPattern The array of consecutive pair values of the dash length and the gap length. * @param[in] dashPattern The array of consecutive pair values of the dash length and the gap length.
* @param[in] cnt The length of the @p dashPattern array. * @param[in] cnt The length of the @p dashPattern array.
* @return Result::Success when succeeded, Result::FailedAllocation or Result::InvalidArguments otherwise. * @retval Result::Success When succeeded.
* @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.
*/ */
Result stroke(const float* dashPattern, uint32_t cnt) noexcept; Result stroke(const float* dashPattern, uint32_t cnt) noexcept;
@ -835,10 +871,10 @@ public:
* The direct loading from a file is available for the svg and png files. * The direct loading from a file is available for the svg and png files.
* *
* @param[in] path A path to the picture file. * @param[in] path A path to the picture file.
* @return Result::Success when succeeded, otherwise the returned value depends on the problem type: * @retval Result::Success When succeeded.
* Result::InvalidArguments - in case the @p path is empty, * @retval Result::InvalidArguments In case the @p path is empty.
* Result::NonSupport - when trying to load a file with an unknown extension, * @retval Result::NonSupport When trying to load a file with an unknown extension.
* Result::Unknown - if an error occurs at a later stage. * @retval Result::Unknown If an error occurs at a later stage.
*/ */
Result load(const std::string& path) noexcept; Result load(const std::string& path) noexcept;
@ -849,10 +885,10 @@ public:
* *
* @param[in] data A pointer to a memory location where the content of the svg file is stored. * @param[in] data A pointer to a memory location where the content of the svg file is stored.
* @param[in] size The size in bytes of the memory occupied by the @p data. * @param[in] size The size in bytes of the memory occupied by the @p data.
* @return Result::Success when succeeded, otherwise the returned value depends on the problem type: * @retval Result::Success When succeeded.
* Result::InvalidArguments - in case no data are provided or the @p size is zero or less, * @retval Result::InvalidArguments In case no data are provided or the @p size is zero or less.
* Result::NonSupport - when trying to load a file with an unknown extension, * @retval Result::NonSupport When trying to load a file with an unknown extension.
* Result::Unknown - if an error occurs at a later stage. * @retval Result::Unknown If an error occurs at a later stage.
*/ */
Result load(const char* data, uint32_t size) noexcept; Result load(const char* data, uint32_t size) noexcept;
@ -865,19 +901,24 @@ public:
* @param[in] w The width of the image in pixels. * @param[in] w The width of the image in pixels.
* @param[in] h The height of the image in pixels. * @param[in] h The height of the image in pixels.
* @param[in] copy Specifies the method of copying the @p data - shallow if @c false and deep id @c true. * @param[in] copy Specifies the method of copying the @p data - shallow if @c false and deep id @c true.
* @return Result::Success when succeeded, otherwise the returned value depends on the problem type: * @retval Result::Success When succeeded.
* Result::InvalidArguments - in case no data is provided or the width or the height of the picture is zero or less, * @retval Result::InvalidArguments In case no data is provided or the width or the height of the picture is zero or less.
* Result::NonSupport - when trying to load a file with an unknown extension. * @retval Result::NonSupport When trying to load a file with an unknown extension.
*/ */
Result load(uint32_t* data, uint32_t w, uint32_t h, bool copy) noexcept; Result load(uint32_t* data, uint32_t w, uint32_t h, bool copy) noexcept;
/** /**
* @brief ... * @brief Gets the position and the size of the loaded picture.
* @param[out] x *
* @param[out] y * For the svg file the returned values are specified in the viewBox attribute.
* @param[out] w * For the png and raw files, @p x and @p y are zeros and @p w and @p h indicate the width
* @param[out] h * and the height of the picture, respectively.
* @return Result::Success when succeeded, ... otherwise. *
* @param[out] x The horizontal coordinate of the upper left corner of the picture.
* @param[out] y The vertical coordinate of the upper left corner of the picture.
* @param[out] w The picture width.
* @param[out] h The picture height.
* @return Result::Success when succeeded, Result::InsufficientCondition otherwise.
*/ */
//TODO: Replace with size(). Remove API //TODO: Replace with size(). Remove API
Result viewbox(float* x, float* y, float* w, float* h) const noexcept; Result viewbox(float* x, float* y, float* w, float* h) const noexcept;
@ -951,7 +992,7 @@ public:
Result push(std::unique_ptr<Paint> paint) noexcept; Result push(std::unique_ptr<Paint> paint) noexcept;
/** /**
* @brief Sets the size of the memory block, 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 * If the number of objects pushed into the scene is known in advance, calling the function
* prevents multiple memory reallocation, thus improving the performance. * prevents multiple memory reallocation, thus improving the performance.
@ -985,7 +1026,7 @@ public:
* *
* @ingroup ThorVG * @ingroup ThorVG
* *
@brief description... * @brief A class for the rasterisation of graphic elements with a software engine.
* *
*/ */
class TVG_EXPORT SwCanvas final : public Canvas class TVG_EXPORT SwCanvas final : public Canvas
@ -998,24 +1039,30 @@ public:
*/ */
enum Colorspace enum Colorspace
{ {
ABGR8888 = 0, ///< ABGR8888 = 0, ///< The channels are joined in the order: alpha, blue, green, red.
ARGB8888 ///< ARGB8888 ///< The channels are joined in the order: alpha, red, green, blue.
}; };
/** /**
* @brief ... * @brief Sets the target of the rasterisation.
* @param[in] *
* @param[in] * The buffer of a desirable size should be already allocated.
* @param[in] *
* @param[in] * @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] * @param[in] stride The stride of the raster image - greater than or equal to @p w.
* @return Result::Success when succeeded, ... otherwise. * @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 Result::Success when succeeded.
* @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 enabled in the 'meson_options.txt' file.
*/ */
Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept; Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept;
/** /**
* @brief ... * @brief Creates a new SwCanvas object.
* @return Result::Success when succeeded, ... otherwise. * @return A unique pointer to the new SwCanvas object when succeeded, @c nullptr if the software engine is not enabled in the 'meson_options.txt' file.
*/ */
static std::unique_ptr<SwCanvas> gen() noexcept; static std::unique_ptr<SwCanvas> gen() noexcept;
@ -1028,7 +1075,7 @@ public:
* *
* @ingroup ThorVG * @ingroup ThorVG
* *
* @brief description... * @brief A class for the rasterisation of graphic elements with the OpenGL engine.
* *
*/ */
class TVG_EXPORT GlCanvas final : public Canvas class TVG_EXPORT GlCanvas final : public Canvas
@ -1037,19 +1084,14 @@ public:
~GlCanvas(); ~GlCanvas();
/** /**
* @brief ... * @brief Sets the target of the rasterisation.
* @param[in]
* @param[in]
* @param[in]
* @param[in]
* @return Result::Success when succeeded, ... otherwise.
*/ */
//TODO: Gl Specific methods. Need gl backend configuration methods as well. //TODO: Gl Specific methods. Need gl backend configuration methods as well.
Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h) noexcept; Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h) noexcept;
/** /**
* @brief ... * @brief Creates a new GlCanvas object.
* @return * @return A unique pointer to the new GlCanvas object when succeeded, @c nullptr if the OpenGL engine is not enabled in the 'meson_options.txt' file.
*/ */
static std::unique_ptr<GlCanvas> gen() noexcept; static std::unique_ptr<GlCanvas> gen() noexcept;
@ -1058,33 +1100,36 @@ public:
/** /**
* @class Engine * @class Initializer
* *
* @ingroup ThorVG * @ingroup ThorVG
* *
* @brief description... * @brief A class that enables initialization and termination of the ThorVG engine.
* *
*/ */
class TVG_EXPORT Initializer final class TVG_EXPORT Initializer final
{ {
public: public:
/** /**
* @brief ... * @brief Initializes the ThorVG engine.
* * @param[in] engine The engine type - the same as specified in the 'meson_options.txt' file.
* @param[in] arg ... * @param[in] threads The number of threads - zero is treated as one.
* * @retval Result::Success When succeeded.
* @note ... * @retval Result::InsufficientCondition An internal error possibly with memory allocation.
* * @retval Result::InvalidArguments If unknown engine type chosen.
* @return ... * @retval Result::NonSupport In case the engine type in the 'meson_options.txt' differs from the one specified in the @p engine argument.
* * @retval Result::Unknown Other.
* @see ...
*/ */
static Result init(CanvasEngine engine, uint32_t threads) noexcept; static Result init(CanvasEngine engine, uint32_t threads) noexcept;
/** /**
* @brief ... * @brief Terminates the ThorVG engine.
* @param[in] arg ... * @param[in] engine The engine type - the same as specified in the 'meson_options.txt' file.
* @return ... * @retval Result::Success When succeeded.
* @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 in the 'meson_options.txt' differs from the one specified in the @p engine argument.
* @retval Result::Unknown Other.
*/ */
static Result term(CanvasEngine engine) noexcept; static Result term(CanvasEngine engine) noexcept;