Mark implementation

[heckj]

Mark

Extending into "what and how" of the implementation, Mark is a core consideration of this design.

A mark represents a set of visual shapes (one or more), but more importantly it doesn't represent a single specific shape - with the various parameters applied, but a means to generate those shapes. The mark itself has mappings to describe how data should get transformed into something visual (I'm describing the mapping as VisualChannel in the code).

I initially see two potential options for implementing this such that we get scribbles drawn into a canvas.

1. The first is that we make the Mark responsible for directly drawing into a GraphicsContext provides from a canvas. The idea being that there's a method on Mark that takes a GraphicsContext and data, iterates through the data, and renders symbols at the appropriate positions on the canvas.

2. Another is not to have Mark render directly to the canvas, but generate a series of individual symbols generated by iterating through the data, and those symbols are captured by something above the mark (Chart object, in this case) and it's responsible for rendering those symbols into a GraphicsContext from a Canvas.

In order to know the specific locations of the symbols, the space available to the charting area needs to be known, which means this step of the drawing needs to take into account space for any other visual elements that don't overlap - such as axis, caption, and potentially a legend. In both of the above cases, I'm expecting that the final values are known by the end of this process, and any mapping from upstream data has taken place.

[heckj]

Progress!

With the PR in flight, the most basic versions of going from declaration to rendered graphics is operational. The pattern that I leaned into use was having each mark be responsible for generating data instances that represent the individual symbols, and all the details needed to render them, given a drawing area specified as a CGRect.

The Mark protocol includes the method symbolsForMark(in rect: CGRect) -> [MarkSymbol] that is called upon to do this work. MarkSymbol is an enumeration with associated data in the form of structs that have more details (x, y coordinates, shapes, orientation information, etc) that are purely data focused, and consumed by a ChartRenderer which takes them and renders each of the individual symbols into a GraphicsContext provided by SwiftUI's Canvas.

I thought about having each symbol know how to render itself, but opted instead to have the Chart view contain a renderer that has the implementation details. I have a vague idea that this allows different renderers to be able to be used down the road, which would have otherwise been very awkward to implement if I'd coupled the "what the data is" and "the responsibility to draw" it together into the same instance.

I do rather wish that GraphicsContext had some of the flexibility to render into alternate formats that the older CoreGraphics Context does (to support rendering into an Image format such as PNG or JPEG, or even vector format like PDF). There's no obvious path there currently (feedback submitted: FB10007778). I'm working around it for snapshot testing purposes (using PointFree's Snapshot Testing library and some helper extensions to render the SwiftUI view into an image.

As I'm writing this, I've generated all the data structures for the shapes for dots/points, simple straight lines, and bars for charting, but am only rendering the points currently. The others to be included fully through rendering before I merge the PR. There's no notable test coverage as yet, which remains to be done - and the drawing area is super-basic, without any axis, override capabilities, etc - but it proves the end-to-end flow from declaration with data into a visual canvas.

One of the work items I'm planning on adding quickly after this is complete is a simple benchmark to capturing the time it takes to go from data & declaration to rendered canvas so that I can track that and keep an eye out for unexpected regressions in algorithms or exponential loops. There's a couple in sequence through fairly divorced code sections, which could be easy to do inefficiently or accidentally.

The process of getting this working end-to-end illuminated some limitations (and mistakes) in earlier API structure - and in some of the assumptions I'd made in scale, so various updates have been back-propagated there as well.

[heckj]

Starting into the bits of code that draw and lay out one of more axis on a chart has helped highlight some quandaries for the declaration semantics.

So far I've been tracking the scaling and domains of input for each mark with that mark - so if you declared something like:

Chart {
   Point(data, x: \.value, y: \.anothervalue).scale(.log)
   Point(otherdata, x: \.value, y: \.anothervalue)
}

The two marks would each have their own scales and map into the space available, basically ignoring each other.
But now that I'm starting in on displaying an Axis, we can get into pathological use cases that just don't make sense. For example, in the following declaration:

Chart {
   Point(data, x: \.value, y: \.anothervalue).scale(.log).xAxis()
   Bar(otherdata, x: \.value, y: \.anothervalue).xAxis()
   Line(data, x: \.value, y: \.something).xAxis()
}

What would you expect to happen? They can't all display on the xAxis without terribly muddling things - although maybe that's appropriate. But in the case of the Point and Line above, they're using the same data source - with different scales (linear vs log) - so should the domains and scales be combined?

Do we go with "whatever defined the first (or last) .xAxis() wins" kind of scenario? Or should all three attempt to draw an axis, and muddle it up because that's what the declaration appears to ask to do? There is a use case where we'd like to have two X axis - one drawn on the bottom, and a second on top - so there's room in a standard 2D chart for two.

Is there a case where you'd merge the domains of the incoming values, using a coordinated scale to display values from two data sources together in the same chart?

[heckj]

One of the constraints of using Result Builders within swift is that there isn't a good way to report back "This combination is non-sensical" in such a way that the compiler can provide a meaningful message, and an exception during the "building" process doesn't get positively reflected either - that's a whole runtime thing, where the rest of the DSL is a compilation-time thing.

So far, I've been leaning into "make it always work" so that any valid syntax will always create some visual, even if that visual is muddy and confused, rather than erroring out (crashing) or throwing an exception. If something is mandatory, then it's included as a parameter where you can make it mandatory - and apply defaults over it if needed.

As I started with axis, I had this idea that one of the marks defined the axis, and that it was something that was "reduced" from the set of marks up to a chart-level thing. But that begs the question of applying that axis (and its scale) to other marks. So along those lines, maybe the axis is something specific to a mark - and if you're wacky enough to apply one to each mark, they'll attempt to overlay each other and both get drawn.

In that scenario, the default is that each mark is separate - so is there a scenario where you might want to merge the domains for two marks into the same, and use a combined axis and scale to represent them together? If so, how should that be defined?