Hooray wrote in Fri Feb 26, 2016 5:08 pm:In fact, let's face it - you, too, faced quite a steep learning curve when you first tinkered with Canvas despite having an unprecedented track record of working with rendering/graphics code, and all the solid math expertise to understand what a translation is, what a transformation is and what they have in common - and still, we exchanged a bunch of messages to get you going - you stated a few times that the documentation/examples and snippets were lacking, and that you needed to know how to do certain things - and even in this very thread, we're still posting snippets that you are incorporating directly in your code, as we can see in your commits.
This should actually give you pause - if someone who can read Nasal and understands real time rendering and can get up to speed with the C++ rendering code to add tree shadows in a few days can not figure out how to use canvas from the Wiki and the code snippets, then maybe there's a problem with the documentation.
In fact, the missing link is that I have no solid idea what concepts canvas is based on, I'm only gradually developing it by trial and error.
Consider the simple example of making a gauge - I have a rectangle in an SVG mask and want to fill it with a colored bar with its height given by the quantity to display.
What's documented is that I can do
- Code: Select all
svg.getElementById("myRectangle");
to get a handle to the element. So what then? What precisely is it I have at the other end of this handle? In the SVG file, there's a gazillion of properties characterizing the rectangle:
- Code: Select all
<rect
style="opacity:1;fill:#00ff00;fill-rule:nonzero;stroke:#ffffff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
id="myRectangle"
width="16.9748"
height="60.7747"
x="358.577"
y="170.425" />
How do they map into what canvas has? I do not know. Is it broken down into four lines? Are the vertex coordinates accessible as an array somewhere? Are width and height accessible? Are the linejoin settings used at all? I do not know.
In fact, the SVG files which I got from Gijs came with both defined clipping regions, and some of them apparently have a slot for animation (aka, their coordinates have an open z-parameter).
Can I use any of this in canvas? If yes, what would be the call to set them? I do not know.
When I load the file, I get an error about 'noneff' not being known. What is a noneff? I do not know.
By patient trial and error, bisecting the SVG and removing properties one by one, I came to understand that the error emerges when the SVG contains a stroke color of 'none' and an opacity of 1, so it would seem canvas tries to string-join hex color and an opacity of ff to get 'none~ff' - which doesn't seem map into a valid coloring request.
Looking into the canvas docs, I can find about accessing SVG:
- Code: Select all
# change the background color
myCanvas.set("background", "#ffaac0");
# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";
var svg_symbol = root.createChild('group');
canvas.parsesvg(svg_symbol, filename);
svg_symbol.setTranslation(width/2,height/2);
#svg_symbol.setScale(0.2);
#svg_symbol.setRotation(radians)
So I can apply translations, rotations and scales - is this all? No, it is not all, because I can also set colors and fill colors. Can I set yet more? I do not know. Can I access the coords of my rectangle directly? I do not know. Can I make use of what seems to be pre-defined motions inside the SVG structure? I do not know.
There's a hidden assumption somewhere that everyone knows these things, that everyone knows what the SVG internally is, what properties it stores and what of that is transferred to canvas when parsing. That everyone is clear on how the group hierarchy works, what properties can be set for whole groups, what are so special that they can't.
I have no trouble finding snippets of this and that on the wiki, quotes copied over from some context which doesn't quite fit, all that. What I can't find is solid documentation. There's no common thread, no big picture, no document outlining the specs.
Yes, I can read api.nas - but I can't figure out easily what an SVG element becomes after I parsed it, aka what section of it applies to my particular use case.
What's missing is like "This is a comprehensive lists of all elements which canvas knows. This is a comprehensive list of properties and methods you can use for element X. This is a list of how SVG elements are mapped into canvas elements. These are the valid ranges for the parameters you can set."
Let me finally quote Durk from the mailing list who seems to echo some of my sentiments:
I've been rather shocked by the current state of affairs on the
flightgear wiki. Somebody seems to think that excessive quoting equates
documentation, but unfortunately makes the wiki close to useless.
Additionally, there are far too many stubs and outdated articles to make
the wikie useful. Wouldn't it be time to initiate a major clean-up?