Update 14 March, 2017: FSDL has been modified with the release of Frogans Player for developers alpha (v1.4.1), in particular with modifications to the values of the “visible” attribute in the <layer> element. The contents of this post and the downloadable resources have been updated accordingly.
Click here to download a Frogans site that uses the examples shown in this post.
With the <respath> element, you can create a resource by plotting sets of XY coordinates as “anchor points.” Frogans renders the resource by drawing lines along these anchor points to create a vectorized shape.
For example, a rectangle can be determined by plotting four anchor points, one for each corner.
2. The <respath> element and its attributes
Let’s create a simple rectangle using <respath> in FSDL 3.0 .
First, let’s create an empty <respath> element in an FSDL file:
<?xml version='1.0' encoding='utf-8'?> <!-- This is your XML declaration --> <frogans-fsdl version='3.0'> <!-- The opening tag of your FSDL root element --> <respath resid='MYpath_1_r' size='640,480' crop="auto" stroke='on' spread='off' color='#00BB00'> <!-- Plot your coordinates here --> </respath> </frogans-fsdl><!-- The closing tag of your FSDL root element -->
Before plotting the coordinates, let’s look at the attributes included here in the <respath> :
“resid” (required) – the value of this attribute (‘MYpath1’) is the name that you give the graphic resource that is created;
“size” (required) – the value of this attribute (‘640,480’) determines the rendered size in pixels of the resulting graphic resource; the final size displayed on the device can vary, depending on the resolution of the screen;
“crop” (required) – the value of this attribute (‘auto’) frames a bounding box around your path, kind of like a page setup; the value of “auto” automatically crops the bounding box according to the dimensions of your path;
“stroke” (required) – the value of this attribute (‘off’) determines if the graphic resource will be rendered as stroke along the path (‘on’) or as a fill of the area inside the path (‘off’);
“spread” (required) – the value of this attribute (‘off’) determines whether the graphic resource will be stretched to match the dimensions of the size (‘on’), or if it will maintain its original proportions;
“color” (optional) – the value of this attribute (‘#00BB00’) determines the fill color of the shape (if “stroke=’off'”) or the color of its stroke (if “stroke=’on'”);
3. Plotting anchor points in <respath>
Now let’s sets of coordinates to determine the anchor points for a simple rectangle:
<respath resid='MYpath_1_r' size='640,480' crop="auto" stroke='off' spread='on' color='#00BB00'> Ju:0,0; Li:20,0; Li:20,20; Li:0,20 </respath>
Notice how each coordinate pair is preceded by either “Ju:” or “Li:”?
“Ju” says that the following anchor point is a “jump item,” meaning that it designates the start of a path.
“Li” says that the following anchor point is a “linear item,” meaning that a straight line will be drawn from the previous anchor point to this one.
To see this resource on a Frogans slide, let’s present it in a <layer> element:
<layer resref='MYpath_1_r' layerid='MYpath_1_l' leapout='a' pos='0,0' align='left-top' combine='add' opacity="100" />
Here’s a screenshot of the rendered slide (on an orange-colored desktop background):
You might have expected this rectangle to be a perfect square since, according to the coordinates of the vertices, each side is 20 units long. Instead, it is rendered to match the value of the “size” attribute of ‘640,480,’ or on this standard monitor, 320 by 240 pixels. This is because the value of the “spread” attribute is ‘on.’
If the value of the “spread” attribute is instead set to ‘off,’ then our rectangle will fill up the “size” of the resource as much as possible, but it will retain its original perfect square proportions:
To better see how our square fits in a 640 by 480 resource, let’s put a 640 by 480 checkerboard in a layer behind it:
4. Scaling, using the size attribute
As you can see, the “size” attribute in the <respath> element determines the rendered size of the graphic resource. The shape that you create will stretch to match the dimensions set in “size” if the “spread” attribute has a value of ‘on.’ Otherwise, if the value of “spread” is ‘off,’ then the shape is scaled to best fit the “size” while maintaining its original proportions.
This means that, when the value of “spread” is ‘off,’ you can isometrically scale your shape up or down simply by changing the height or width of the resource in the value of the “size” attribute.
For example, if the width were made much narrower, the square would scale down accordingly. If we set the value of “size” to ‘200,480’ (and did the same with the checkerboard background):…
Since the resource being much more narrow than it is tall, the square is sized to fit in its width. Ideally, you want to set your size to best match the shape of your path, so that Frogans Player does not devote unnecessary resources to rendering your graphic resource.
5. Compound shapes
A compound shape is one in which the transparency of intersecting areas is reversed, i.e., opaque areas become transparent and transparent areas become opaque.
For example, you could draw a 5-pointed star by plotting five anchor points in such a way that the lines that join them cris-cross each other. If this shape is not compound, then it will appear as a solid form. But if it is a compound shape, the center of the star will appear to be hollow.
You can set your path to create a compound shape with the “fill” attribute in the <setpath> element. By default, “fill=’non-zero’,” so that it is not a compound shape. To make it a compound shape, set the value of “fill” to ‘even-odd’.
5.1 Compound shapes using multiple path segments
You can also create multiple path segments in a single <respath> element. These path segments can combine together as a compound shape. Imagine that you drew the capital letter “A” using <respath>. You would do this using two path segments: One for the outer shape of the letter, and one for the triangular hole in the center.
To more simply illustrate this, let’s work with a square and a triangle, where the triangle cuts a hole in the square. In <respath> you can create a new path segment by starting it with the “Ju:” jump item. The following code creates a square path segment and a triangle path segment in the same <respath> element:
<respath resid='MYpath_1_r' size='640,480' crop="auto" stroke='off' spread='off' color='#00BB00' fill='even-odd' > Ju:0,0; Li:20,0; Li:20,20; Li:0,20; Ju:10,5; Li:15,15; Li:5,15 </respath>
Note that, since “fill=’even-odd’,” we can expect that the triangle creates a transparent hole in the square.
Here’s the result:
An important thing to note is that you do not necessarily need to set the “fill” attribute to ‘even-odd’ to create this effect with multiple path segments. We can get the same effect by reversing the direction of one of the two path segments. In the above example, the anchor paths for the two path segments are plotted in a clockwise direction. So, if the triangle is plotted in the opposite direction and the “fill” attribute has its default value of ‘non-zero’ (or isn’t included at all), then we should get the same result as in the example above. Here’s the new code:
<respath resid='MYpath_1_r' size='640,480' crop="auto" stroke='off' spread='off' color='#00BB00' fill='non-zero' > Ju:0,0; Li:20,0; Li:20,20; Li:0,20; Ju:10,5; Li:5,15; Li:15,15 </respath>
That’s enough for this post, but the adventure continues with Drawing vector shapes with <respath> in FSDL (pt. 2 – CURVES!), which covers curved paths and how to get complex paths from SVG files into you FSDL files.
Click here to download a Frogans site that uses these examples.