﻿<?xml version='1.0' encoding='utf-8' ?>
<?xml-stylesheet type="text/xsl" href="header_e.xsl" ?>
<body PageTitle="Svgtex - XML shortcuts" PageHeader="Tutorials" Created="2010-03-23" Updated="2010-03-23">
<div>
<span><b>XML shortcut</b> is a small file, which directs <b>svgtex</b> plugin to the source SVG file(s). They
can be used to compose from a single <em>*.svg</em> file many different textures, and enrich them with 
additional effects.
</span>
<br/>
<span>
To follow this section, you should be at least familiar with the basics of XML syntax and conventions.
You can learn it from many sources in the Web. There is a <a href="http://en.wikipedia.org/wiki/XML" title="artykuł o XML">page about it</a>
in Wikipedia, for example. Read that text and analyze the examples, for a while. It should be enough.
</span>
<p/>
Would you like to repeat the actions, shown in the text below? Download the exemplary model:
<br/>
<a href="downloads/p40b.zip" title="model, used in this and the next">the example</a> — a P-40B model, with textures, used in this text (the same as in the first part of svgtex description);
<p/>
</div>
<div class="subheader">1. Simplest case</div>
<div>
<span>Let's begin with the simplest case: do you remember from 
<a href="scripts-svgtex1_e.xml" title="first part of svgtex description">svgtex parameters details</a>, 
that the length of the path to the source file (<b>File Name</b> field in <b>Plugin</b> panel) can 
have up to 63 characters? To use longer paths, create a new <em>*.xml</em> file (just in the Notepad, for example). 
Its content should have structure like on <b>Fig. 1.1</b>:
</span>
<br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<A href="images/scripts/svgtex2/image11.xml" target="_blank" title="click, to open this XML file">
				<IMG src="images/scripts/svgtex2/image11_e.png" align="right"/>
			</A>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 1.1 Simple XML shortcut to a SVG file (the path is longer than 63 characters)</spanl></td>
	</tr>
</table>
<p/>
</div>
<div>
<span>
All elements in this XML should have the <b>tex:</b> namespace prefix, otherwise will be ignored.
The root node - <b>tex:texture</b> - is always the same. It contains just simple <b>tex:src</b>
reference. Type the path to the SVG file into value of its <b>path</b> attribute. You can use paths 
up to 1023 characters, here.
</span>
<br/>
<span>
Name this file <em>nor_details.xml</em>. Place it in the folder, where the actual <em>*.blend</em>
file is located. When you type "<em>nor_details.xml</em>" into plugin <b>File Name</b> field, the 
miniature of the <b>skin.svg</b> picture should appear in the <b>Preview</b> panel (<b>Fig. 1.2</b>).
This is the evidence that the shortcut is working properly:
</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<IMG src="images/scripts/svgtex2/image12_e.png" align="right"/>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 1.2. Usage of the <em>nor_details.xml</em> shortcut</spanl></td>
	</tr>
</table>
</div>
<div class="subheader">2. Using SVG file as picture library</div>
<div>
<span>Nearly all raster textures of P-40 model, used as the example here, have been created as 
a composition of some layers from <em>skin.svg</em> file. Many of these layers were used
more than once. For an illustration, let's have look at the <b>B.Skin.Holes</b> texture. It maps
small holes on the aircraft skin, and use this picture to alternate the material's opacity (alpha) value.
<b>B.Skin.Holes</b> uses <em>holes.png</em> raster image, which has been composed from two layers of 
<em>skin.svg</em>: <b>Holes</b> and <b>Bkg-White</b> (<b>Fig. 2.1</b>). Result of this composition
has been exported from Inkscape to the raster file:</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<IMG src="images/scripts/svgtex2/image21_e.png" align="right"/>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 2.1 Composition of the airplane skin holes: layers <b>Holes</b> + <b>Bkg-White</b></spanl></td>
	</tr>
</table>
<p/>
<small>To make the <b>Fig. 2.1</b> clearer, I also have turned on the visibility of the UV layer.
It contains the UV unwraps of the Blender meshes. The size and location of the holes is obvious,
when you can see these meshes below.</small>
<p/>
<span>From the same <em>skin.svg</em> file comes the picture for the bump map texture - <em>nor_details.png</em> file.
It is composition of many layers, and each of them has different opacity setting. To simplify the 
export to the raster image, I have decided to place clones of these layers to a single layer: 
<b>Result:Nor-Details</b>. Then the resulting raster image - <em>nor_details.png</em> - is exported
as composition of <b>Result:Nor-Details</b> and <b>Bkg-Grey</b> layer(<b>Fig. 2.2</b>):
</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<IMG src="images/scripts/svgtex2/image22_e.png" align="right"/>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 2.2 Composition of the bump map: <b>Result:Nor-Details</b> + <b>Bkg-Grey</b></spanl></td>
	</tr>
</table>
<p>The <em>skin.svg</em> file, with layer visibility set as on <b>Fig.
2.2</b>, we have used in the previous example (compare the texture preview on <b>Fig.
1.2</b>).</p>
<span>XML shortcuts allow to use source <em>*.svg</em> drawing as something like "image library". 
The same <em>skin.svg</em> file, used in the previous example as the bump map 
(in <b>B.Skin.Nor-Details</b> texture — see <b>Fig. 1.2</b>), we will use here again.
We use it as the source for the holes texture (<b>B.Skin.Holes</b>), without applying any 
changes to the source SVG picture. <b>Fig. 2.3</b> shows the content of <b>holes.xml</b> shortcut,
which creates this effect:</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<A href="images/scripts/svgtex2/image23.xml" target="_blank" title="click, to open this XML file">
				<IMG src="images/scripts/svgtex2/image23_e.png" align="right"/>
			</A>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 2.3 XML shortcut, alternating layers visibility in the source SVG file.</spanl></td>
	</tr>
</table>
<p>Comparing to the previous example (<b>Fig. 1.1</b>), the <b>tex:src</b> node
contains here some new <b>tex:override</b> elements. The role of <b>tex:src</b> is to 
point the parser the source SVG file to load. The role of each <b>tex:override</b> is
to alternate some properties of particular element from the source SVG file. The id of the "target" 
for this alternation is specified in <b>for</b> attribute value. On the example from <b>Fig. 2.3</b>,
first two <b>tex:override</b> elements turn off visibility (<em>display=”none”</em>) of <b>Bkg-Grey</b> and <b>Ref:Nor-Details</b> layers.
The next two <b>tex:override</b>s are used to turn on visibility (<em>display=”inline”</em>)
of of <b>Bkg-White</b> and <b>Holes</b> layers. Propagation of these changes to the target element's children nodes
is controlled by the <b>propagate</b> attribute. In this example, propagation is turned off - their visibility
does not matter, when their "parent" becomes invisible.</p>

<span><b>Fig. 2.4</b> shows the result of <em>holes.xml</em> shortcut:</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<IMG src="images/scripts/svgtex2/image24_e.png" align="right"/>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 2.4. Content of <em>skin.svg</em>, „filtered” by the <em>holes.xml</em> shortcut</spanl></td>
	</tr>
</table>
<p/>
<span>Notice, that in the example above I have typed id of layer <b>Bkg-Grey</b> as <em>„layer5”</em>,
<em>„layer19”</em> for <b>Result:Nor-Details</b> layer, and so on. How do I know that they have such ids?
You have to find them in the source SVG file (<b>Fig. 2.5</b>):</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<IMG src="images/scripts/svgtex2/image25_e.png" align="right"/>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 2.5 Discovering in SVG source the <b>id</b> value of the layer, found by the name</spanl></td>
	</tr>
</table>
<p/>
<span>Open the SVG file in a web browser (Firefox, for example). Open the context menu and select
the <b>View page source</b> command. In the source editor window press <b>Ctrl-F</b> (<em>Find</em>),
and find the layer definition, using its name (<b>Fig. 2.5b</b>). The <b>id</b> attribute is 
the unique identifier of this element, referenced by <b>tex:override</b>.</span>
</div>
<div class="subheader">3. XML shortcuts format</div>
<div>
<li><big><b>tex:texture</b></big> element is always the root of XML shortcut document (<b>Fig. 1.1</b>).
Except <b>tex:</b> namespace declaration (<b>xmlns</b> attribute) it has not any attributes.
<b>tex:texture</b> contains one (or more) <b>tex:src</b> elements. You can also place any other
SVG element there (without any namespace prefix).
</li>
<li>
<big><b>tex:src</b></big> element tells the interpreter to load a source SVG file. Its full name is placed in the 
<b>path</b> attribute, and can have up to 1023 characters. <b>tex:src</b> can contain zero 
or more <b>tex:override</b> elements.
</li>
<li>
<big><b>tex:override</b></big> element alternates the properties (attribute values) of an element in the SVG source file (pointed
by the parent <b>tex:src</b>). The identifier (<b>id</b>) of this "target" node has to be specified
in the mandatory <b>for</b> attribute. Additionally, <b>tex:override</b> should contain some SVG attributes,
alternating the corresponding values of the "target" element (<b>display</b>, for example). The mandatory
<b>propagate</b> attribute specifies the alternation scope. When <b>propagate</b>=”<em>all</em>”, it 
alternates the target element and all its descendants. When <b>propagate</b>=”<em>none</em>”, the children of the target 
remain unaltered. 
</li>
<p/>
</div>
<div>
<span>
In general, you can place in a <b>tex:override</b> node all style attributes, described in the 
<a href="http://www.w3.org/TR/SVG11" title="offical w3.org SVG specification">SVG 1.1 specification</a>. 
I have listed below the names of the most typical SVG properties to be overridden:
</span><br/>
<ul>
<li><b>display</b>: visibility of the element (visible when <em>display=”inline”</em>, invisible when <em>display=”none”</em>);</li>
<li><b>opacity</b>: general element opacity — a number from 0.0 to 1.0 range. For example: <em>opacity=”0.5”</em> means 50% of transparency;</li>
<li><b>fill</b>: fill color (for example <em>fill=”#080808”</em> fill contours with grey color, that contains 50% of the black);</li>
<li><b>fill-opacity</b>: opacity, that has no influence on the stroke — a number from 0.0 to 1.0. For example <em>fill-opacity=”0.6”</em> 
means that the contour interior has 40% of transparency;</li>
<li><b>stroke</b>: color of the borderline (for example <em>stroke=”#080000”</em> gives dark red border);</li>
<li><b>stroke-opacity</b>: opacity of the border — a number from 0.0 to 1.0 range;</li>
<li><b>stroke-width</b>: the width of the borderline — any positive number;</li>
<li><b>stroke-dasharray</b>: a reference to a dash pattern (details — see the SVG specification);</li>
<li><b>font</b>: a reference to a font definition (used in text element) (details — see the SVG specification);</li>
<li><b>font-size</b>: an positive number, with optional unit (details — see the SVG specification);</li>
<li><b>filter</b>: a reference to filter definition (details — see the SVG specification);</li>
<li><b>mask</b>: a reference to mask definition (details — see the SVG specification);</li>
<li><b>clip-path</b>: a reference to path element that "clips" the drawing (details — see the SVG specification);</li>
</ul>
<p/>
<span><b>Fig. 3.1</b> is another example of XML shortcut. It presents some of the rules, described above.
(Names of the SVG source files: <em>t.svg</em> i <em>w.svg</em> do not refer to any existing entities.
This is just the example of some syntax structures, only.):</span><br/>
<table cellSpacing="0" cellPadding="0pt" align="center">
	<tr align="center" valign="top">
		<td>
			<IMG src="images/scripts/svgtex2/image31_e.png" align="right"/>
		</td>
	</tr>
	<tr align="center" valign="top" >
		<td><spanl>Fig. 3.1 Example of an advanced XML shortcut</spanl></td>
	</tr>
</table>
<p>This shortcut composes pictures from two drawings: <em>t.svg</em> and <em>w.svg</em>. (This is
a case of multiple <b>tex:src</b> elements). In addition, there is a filter definition (inside the
<b>defs</b> group. It is a Gaussian blur effect, having identifier (<b>id</b>) = "Blur3". This effect
is used to blur content of the <em>t.svg</em> picture. Id is done by the first <b>tex:override</b> 
element (with attribute <em>filter=”#Blur3”</em>). Notice, that this <b>tex:override</b> has in
<b>for</b> attribute the <b>id</b> of its own parent element (the <b>tex:src</b> node with <em><b>t</b>="t"</em>).
It is also allowed.
</p>
<p>Well, if you have reached this paragraph, dear Reader, it means that you are a programmer
or - at least - have the programmer's inclinations. Would you like to write in Python a nice
GUI gadget that will enable ordinary users to create XML shortcuts? The xml parser is among Python
standard packages, there are also some windowing environments around... Personally I do not need it,
so I have not written such thing, yet!</p>
</div>
</body>
