Drawing format specific coordinate spaces

[thehuglet]

Problem

The current implementation assumes the terminal cell space as the coordinate space for all drawing functions, which is why non-standard drawing functions tend to use f32s for the x and y arguments.

This implementation can be tricky to work with.

Solution

I'm thinking whether tiny coordinate space conversions could be used here effectively. I particularly like the idea of being able to reason about the local coordinate space in integers and having a nice alternative to magic mul/div operations right before drawing.

Alternatives

Alternatively we could explore making drawing functions operate directly on their own local coordinate space. Though I'm, not sure if this is the better solution or not.

This is somewhat related to #3.

[airblast-dev]

Using floating point integers seems pretty rare outside these specific cases.

Maybe its not super efficient but we could pass the coordinates as integers, and the tiny coordinate space could be represented with a range of 0.0..=1.0. In total we would pass 4 values as coordinates, 2 for terminal cells, 2 for inside the cell.

[thehuglet]

Interesting idea, I suppose it could be a bit more explicit this way, would have to see in practice though.

I've started developing a small project on the side to further test the public API and I don't know if I'm happy with using floats for sub-positions. I often find myself confused with the associated magic offsets, especially for octads where I tend to operate on 0.25 and 0.5 steps on the x and y axis respectively to target a specific sub-cell position.

---

I have an idea, but I'm not sure whether this is a good idea or not, so I would appreciate your feedback on this:

I thought of swapping the x and y parameters in all relevant drawing functions for dedicated coordinate space wrappers. Drawing functions would operate on an integer-based coordinate space that makes the most sense for the format they draw, e.g. for twoxels, each increment of y would move down half a cell, creating a more 1:1 grid.

Impl From<T> could also allow relative conversions between coordinate spaces.

What are your thoughts on this specific approach?

[airblast-dev]

I've started developing a small project on the side to further test the public API and I don't know if I'm happy with using floats for sub-positions.

Awesome!
I agree that using floats here doesn't feel super good.

What are your thoughts on this specific approach?

I think that's probably one of the best ways to deal with it. Other libraries I have seen also take that approach.

I would have get a feeling of what can be done for floating points but I think this is in the right direction.

[thehuglet]

I've been thinking of how we could implement this while still keeping the API ergonomic and I came up with the following approach:

Drawing functions would take pos: impl Into<T>, where T is the coordinate space expected by that function (NativePos, TwoxelPos, OctadPos, BlocktadPos). Any passed coordinate type will be converted into the target space automatically. We can also allow tuple (i16, i16) conversions for convenience.

Proposed API examples

// Tuple conversion
draw_text(&engine, layer, (10, 5), "Hello!");

// Drawing text using a TwoxelPos will implicitly convert NativePos here
let pos = TwoxelPos::new(10, 10); 
draw_text(&engine, layer, pos, "foo");

// We could also add some helpers for offsetting x and y
let native_pos = NativePos::new(12, 3);
let pos = TwoxelPos::from(native_pos).offset_y(1);
draw_twoxel(&engine, layer, pos, Color::PINK);

This would also allow developers to implement their own coordinate spaces and conversions quite easily.

[airblast-dev]

Normally I am against From<T> as function bounds as a user can implement it externally on their own type.

In some cases it also allows very type inference heavy code to work. While this sounds good, in practice it means even something like implementing From<T> for an unrelated type can cause breaking changes as it breaks inference.

That said, it does add value here so I am not really sure. I don't really like the idea but I also can't think of anything better either.

[thehuglet]

Oh, sorry for the confusion! By pos: impl Into<T> I didn't mean literally making T generic. I just meant each function has a specific target type, like impl Into<NativePos> for draw_text() or impl Into<TwoxelPos> for draw_twoxel().

I'll remember to avoid using T as a placeholder in the future and use ... instead.

[airblast-dev]

No worries, I did understand what you mean correctly. I just don't like it because it causes confusion and implicit conversions all over the place. Again, I am not super against it but I don't really like it tbh.

[thehuglet]

That's a fair stance. I like keeping things explicit as well, which is why I haven't decided on this yet.

I've been thinking how the impl Into<...> solution would play out in practice and I have a feeling it would be fine for 3 reasons:

• Coordinate spaces are relative to each other. Converting into any coordinate space will result in roughly the same position on screen.
• Implicit conversion is done once at the very end in a draw function. Prior coordinate space operations have to be done explicitly.
• draw_text() already uses impl Into<RichText>, accepting a &str String and RichText by default.

Alternatively we could use the target pos types directly in the parameter, e.g. pos: NativePos. This would be a more explicit solution, but it loses out on API ergonomics, especially for passing in (i16, i16) convenience tuples:

draw_call(&engine, layer, (30, 43).into(), "bar");

[thehuglet]

I experimented with this idea a bit. I overlooked the fact that some conversions like Twoxel -> Native are lossy which can be confusing with an impl From<>.

Thinking of going with explicit .as_*() conversions. I do plan to keep the one-way impl From<(i16, i16)> for FooPosition for convenience though.