Some convenient APIs don't have pub visibility

[unixzii]

There are several APIs that could be made public to improve usability. For example, PathBuilder::cubic_to_pt is currently pub(crate), but it's particularly convenient when the control points are the results of complex manipulations, as it allows passing these point values directly. In contrast, cubic_to requires destructuring points into individual coordinates, which forces me to create temporary variables.

Is there any specific reason why these APIs cannot be public?

[LaurenzV]

I'm not entirely sure, but I would assume that they were simply considered to be implementation details not worth exposing.

[unixzii]

These don't seem to be implementation details, but just wrappers for convenience. They're currently used by stroke dashing internally, but I think exposing them would cause no harm.

tiny-skia/path/src/path_builder.rs

Lines 223 to 234 in 68b198a

	pub fn cubic_to(&mut self, x1: f32, y1: f32, x2: f32, y2: f32, x: f32, y: f32) {
	self.inject_move_to_if_needed();
	self.verbs.push(PathVerb::Cubic);
	self.points.push(Point::from_xy(x1, y1));
	self.points.push(Point::from_xy(x2, y2));
	self.points.push(Point::from_xy(x, y));
	}
	pub(crate) fn cubic_to_pt(&mut self, p1: Point, p2: Point, p: Point) {
	self.cubic_to(p1.x, p1.y, p2.x, p2.y, p.x, p.y);
	}

[LaurenzV]

Oh, I didn't look at the method. Hm, but why does it require you storing the points in a temporary variable? Can't you just do the same like is currently happening in cubic_to_pt? I'm not sure if it's worth adding more methods to the public API just for that single line.

[unixzii]

Take my use case as an example. I hope my code looks like this (simplified):

fn build_some_shape(pb: &mut PathBuilder) {
    // let pt_1 = ...
    // let pt_2 = ...
    // let pt_3 = ...
    pb.cubic_to_pt(some_other_calc(pt_1 + pt_2) + pt_3, ...);
    // ...
}

Without cubic_to_pt, I have to write something like:

fn build_some_shape(pb: &mut PathBuilder) {
    // let pt_1 = ...
    // let pt_2 = ...
    // let pt_3 = ...

    // I now have to come up with a meaningful name for
    // this intermediate result.
    let temp_pt = some_other_calc(pt_1 + pt_2) + pt_3;
    
    pb.cubic_to(temp_pt.x, temp_pt.y, ...);
    // ...
}

In general, cubic_to_pt is particularly useful in cases where you're computing point values on the fly.

[LaurenzV]

Perhaps the best would be to have a single method and let it take a impl Into<Point>. Not sure. But having two methods for this seems a bit superfluous to me.

[unixzii]

Yes, these methods should have been designed to take impl Into<Point> parameters. Unfortunately, the existing versions take individual coordinates, and removing them now would be a breaking change :(

[LaurenzV]

I don't think breaking changes are a problem per se, but I would like to wait for some input from other people before making such a change.

[RazrFalcon]

The reason is simple: Rust doesn't have method overloading or named arguments, therefore making a nice API that works with individual coordinates and points would be clunky.
impl Into<Point> doesn't solve anything, since you would have to write the awkward line_to((5.0, 10.0)) instead of just line_to(5.0, 10.0).

Overall, Point ins't used in public API by design because I haven't been able to make it look nice.
And if someone would decide going the impl Into<Point> route, it means adding those overloads to all types. So not only Path, but also Rect, Transform, etc. That would be a lot of work.

PS: not to mention that impl Into<Point> would also increase the binary size, in theory.