thorvg ThorVG 1.0 official APIs

Finally, the major version of thorvg is going to be changed. This is the opportunity to clear up any mess.

Clear the Experimental APIs
Remove all deprecated APIs
Remove all strings in the paramter
Add a Canvas parameter to all paints gen()

Remove:

[x] Result Picture::viewbox(float* x, float* y, float* w, float* h) const; //experimetal
[x] Result Picture::bounds(float* x, float* y, float* w, float* h) const; //deprecated
[x] Result Picture::load(const char* data, uint32_t size, bool copy = false); //derpecated
[x] Result Canvas::reserve(uint32_t size) //deprecated
[x] Result Scene::reserve(uint32_t size) //deprecated
[x] const uint32_t* Picture::data(uint32_t* w, uint32_t* h) const; //experimetal
[x] Polygon //experimetal
[x] Vertex //experimetal
[x] Result Picture::mesh(const Polygon* triangles, uint32_t triangleCnt); //experimetal
[x] uint32_t Picture::mesh(const Polygon** triangles) const; //experimetal
[x] uint32_t Paint::identifier() const; //deprecated
[x] uint32_t Fill::identifier() const; //deprecated
[x] uint32_t LinearGradient::identifier(); //deprecated
[x] uint32_t RadialGradient::identifier(); //deprecated
[x] uint32_t Shape::identifier(); //deprecated
[x] uint32_t Picture::identifier(); //deprecated
[x] uint32_t Scene::identifier(); //deprecated
[x] uint32_t Text::identifier(); //deprecated
[x] TVG binary format support
[x] Result::Shape::appendArc(float cx, float cy, float radius, float startAngle, float sweep, bool pie) https://github.com/thorvg/thorvg/issues/2632
[ ] Result SwCanvas::mempool(MempoolPolicy policy);

//Discard the plan. Keep this for SVG ~~- [ ] Matrix Fill::transform() const https://github.com/thorvg/thorvg/issues/2859~~ ~~- [ ] Result Fill::transform(const Matrix& m) https://github.com/thorvg/thorvg/issues/2859~~

Modify:

[x] SwCanvas::Colorspace::ABGR8888_STRAIGHT -> SwCanvas::Colorspace::ABGR8888S //experimetal
[x] SwCanvas::Colorspace::ARGB8888_STRAIGHT -> SwCanvas::Colorspace::ARGB8888S //experimetal
[x] enum class StrokeCap -> enum class StrokeCap : uint8_t
[x] enum class StrokeJoin -> enum class StrokeJoin : uint8_t
[x] enum class FillSpread -> enum class FillSpread : uint8_t
[x] enum class FillRule -> enum class FillRule : uint8_t
[x] enum class CanvasEngine -> enum class CanvasEngine : uint8_t
[x] enum Colorspace -> enum Colorspace : uint8_t
[x] enum MempoolPolicy -> enum MempoolPolicy : uint8_t
[x] enum class CompositeMethod -> enum class CompositeMethod : uint8_t
[x] enum SwCanvas Colorspace -> enum Colorspace : uint8_t
[x] Result clear(bool free = true) https://github.com/thorvg/thorvg/pull/1504 https://github.com/thorvg/thorvg/issues/1372
[x] float Shape::stroke(float width) -> float Shape::strokeWidth(float width)
[x] Result Shape::stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) -> Result Shape::strokeFill(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255)
[x] Result Shape::stroke(std::unique_ptr<Fill> f) -> Result Shape::strokeFill(std::unique_ptr<Fill> f)
[x] Result Shape::stroke(const float* dashPattern, uint32_t cnt, float offset = 0.0f) -> Result Shape::strokeDash(const float* dashPattern, uint32_t cnt, float offset = 0.0f)
[x] Result Shape::stroke(StrokeCap cap) -> Result Shape::strokeCap(StrokeCap cap)
[x] Result Shape::stroke(StrokeJoin join) -> Result Shape::strokeJoin(StrokeJoin join)
[x] Result Shape::strokeColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const -> Result Shape::strokeFill(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const
[x] Result Shape::stroke(const float* dashPattern, uint32_t cnt) -> Result Shape::strokeDash(const float* dashPattern, uint32_t cnt, float offset)
[x] Result Saver::save(std::unique_ptr paint, const std::string& path, bool compress) -> Result Saver::save(std::unique_ptr paint, const std::string& path, uint32_t quality = 100)
[x] enum class PathCommand -> enum class PathCommand: uint8_t
[x] Matrix Paint::transform() const -> Matrix& Paint::transform()
[x] Result Picture::load(uint32_t* data, uint32_t w, uint32_t h, bool premultiplied, bool copy = false) -> Result load(uint32_t* data, uint32_t w, uint32_t h, Colorspace cs, bool premultiplied, bool copy = false)
[x] enum class CompositeMethod -> enum class MaskMethod
[x] Result Paint::composite(std::unique_ptr<Paint> target, CompositeMethod method) -> Result Scene::composite(std::unique_ptr<Paint> target, MaskMethod method)
[ ] enum class CompositeMethod::ClipPath -> Result Scene::clip(std::unique_ptr<Paint> clipper); https://github.com/thorvg/thorvg/issues/1496 https://github.com/thorvg/thorvg/issues/2780
[ ] Result Picture::load(const char* data, uint32_t size, const std::string& mimeType, bool copy = false) -> Result::Picture::load(const char* data, uint32_t size, const const char* mimeType, const char* rpath = nullptr, bool delegate = false); //delegate the ownership of the data
[ ] Result Shape::fillColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const -> Result Shape::fill(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const
[ ] SwCanvas::MempoolPolicy -> Initializer::CachePolicy
[ ] uint32_t Shape::pathCommands(const PathCommand** cmds) -> Result Shape::path(const PathCommand** cmds, uint32_t* cmdsCnt, const Point** pts, const uint32_t* ptsCnt);
[ ] uint32_t pathCoords(const Point** pts) const -> Result Shape::path(const PathCommand** cmds, uint32_t* cmdsCnt, const Point** pts, const uint32_t* ptsCnt);
[ ] Result Paint::composite(std::unique_ptr<Paint> target, CompositeMethod method) -> Result Scene::composite(std::unique_ptr<Paint> target, CompositeMethod method)
[ ] CompositeMethod Paint::composite(const Paint** target) const -> MaskMethod Scene::mask(const Paint** target) const
[ ] Result RadialGradient::radial(float cx, float cy, float r) -> Result RadialGradient::RadialGradient::radial(float cx, float cy, float r, float fx, float fy, float fr) https://github.com/thorvg/thorvg/issues/2860

//Discard the plan. Keep this for SVG ~~- [x] Result Shape::fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a); -> Result Shape::fill(uint8_t r, uint8_t g, uint8_t b);~~ ~~- [x] Result Shape::fillColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const -> Result Shape::fillColor(uint8_t* r, uint8_t* g, uint8_t* b) const;~~ ~~- [x] Result Shape::stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a); -> Result Shape::stroke(uint8_t r, uint8_t g, uint8_t b);~~ ~~- [x] Result Shape::strokeColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const -> Result Shape::strokeColor(uint8_t* r, uint8_t* g, uint8_t* b)~~

Promote: (Beta -> Official)

[x] Accessor //Need capi? (v0.10)
[x] Result Shape::order(bool strokeFirst); //Need capi & test
[x] template<typename T> std::unique_ptr<T> cast(Paint* paint)
[x] template<typename T> std::unique_ptr<T> cast(Fill* fill)
[x] SwCanvas::Colorspace::ABGR8888S
[x] SwCanvas::Colorspace::ARGB8888S
[x] float Shape::strokeMiterlimit() const
[x] Result Shape::strokeMiterlimit(float miterlimit)
[x] enum class CompositeMethod::InvLumaMask
[x] class Animation
[x] GlCanvas //Someone is still interested in this backend. https://github.com/thorvg/thorvg/pull/1531
[x] enum class CanvasEngine : Gl //Someone is still interested in this backend. https://github.com/thorvg/thorvg/pull/1531
[x] Result blend(BlendMethod method) const
[ ] std::list<Paint*>& Canvas::paints() const //Need capi?
[ ] std::list<Paint*>& Scene::paints() const //Need capi?

Apr 17 '23 05:04 hermet

@mgrudzinska @JSUYA @mihashco @fire Please take a look at my suggestion and feel free to leave any comments until any issues arise in your projects. Thank you.

May 12 '23 02:05 hermet

godot-git$ git grep "private ThorVG"

modules/text_server_adv/thorvg_bounds_iterator.cpp:53:
// This function uses private ThorVG API to get bounding box of top level children elements.
modules/text_server_fb/thorvg_bounds_iterator.cpp:53:
// This function uses private ThorVG API to get bounding box of top level children elements.

Godot's text server modules appear to use the picture/bounds API: https://github.com/godotengine/godot/blob/master/modules/text_server_adv/thorvg_bounds_iterator.cpp#L53-L70 https://github.com/godotengine/godot/blob/master/modules/text_server_fb/thorvg_bounds_iterator.cpp#L53

May 12 '23 04:05 capnm

godot-git$ git grep "private ThorVG"
modules/text_server_adv/thorvg_bounds_iterator.cpp:53:
// This function uses private ThorVG API to get bounding box of top level children elements.
modules/text_server_fb/thorvg_bounds_iterator.cpp:53:
// This function uses private ThorVG API to get bounding box of top level children elements.
Godot's text server modules appear to use the picture/bounds API: https://github.com/godotengine/godot/blob/master/modules/text_server_adv/thorvg_bounds_iterator.cpp#L53-L70 https://github.com/godotengine/godot/blob/master/modules/text_server_fb/thorvg_bounds_iterator.cpp#L53

Yes, godot uses this one.

Result Paint::bounds(float* x, float* y, float* w, float* h, bool transformed) const noexcept;

We gonna remove this one.

Result Paint::bounds(float* x, float* y, float* w, float* h) const noexcept;

So it's ok.

May 12 '23 04:05 hermet

~@mgrudzinska @JSUYA we are planning to remove the 'alpha' property from the shape since the paint already includes opacity.~

~Result Shape::stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a); -> Result Shape::stroke(uint8_t r, uint8_t g, uint8_t b);~ ~Result Shape::fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a); -> Result Shape::fill(uint8_t r, uint8_t g, uint8_t b);~

~Please let me know if you see any issues from an SVG perspective.~

~Thanks~

May 19 '23 02:05 hermet

ABGR8888S, ARGB8888S (///< @BETA_API) https://github.com/godotengine/godot/blob/master/modules/svg/image_loader_svg.cpp#L100

Promote: (Beta -> Official) ?

May 30 '23 07:05 capnm

please, in the thorvg documentation, decribe in detail the order of bits (lowest and highest, eventually with a formula like for argb : a << 24 | r << 16 | g << 8 | b)

thank you

May 30 '23 08:05 vtorri

ABGR8888S, ARGB8888S (///< @BETA_API) https://github.com/godotengine/godot/blob/master/modules/svg/image_loader_svg.cpp#L100

Promote: (Beta -> Official) ?

@capnm I added them in the promote list. Thanks. :)

May 30 '23 10:05 hermet

please, in the thorvg documentation, decribe in detail the order of bits (lowest and highest, eventually with a formula like for argb : a << 24 | r << 16 | g << 8 | b)

thank you

@vtorri sounds reasonable. https://github.com/thorvg/thorvg/pull/1477

May 30 '23 10:05 hermet

Is there anything needed from Godot Engine?

Jun 29 '23 20:06 fire

Is there anything needed from Godot Engine?

No, so far from the change list, it should not hurt Godot.

Jun 30 '23 01:06 hermet

Releases v0.10.0 external contributor, @martin,

Hi @hermet I just want to let you know, that there is an mistake in the comment on the release. My first name is indeed Martin, but the Github account name is @capnm :-)

Jul 31 '23 19:07 capnm

@capnm yes, I corrected it. Thanks Martin. :-)

Aug 01 '23 01:08 hermet

https://github.com/thorvg/thorvg/issues/1779

Nov 10 '23 05:11 hermet

https://github.com/thorvg/thorvg/wiki/24'-Development-Roadmap

Feb 02 '24 06:02 hermet