diff options
Diffstat (limited to 'share/doc/kicad/help/en/plugins.html')
| -rw-r--r-- | share/doc/kicad/help/en/plugins.html | 2618 |
1 files changed, 2618 insertions, 0 deletions
diff --git a/share/doc/kicad/help/en/plugins.html b/share/doc/kicad/help/en/plugins.html new file mode 100644 index 0000000..1c48c5d --- /dev/null +++ b/share/doc/kicad/help/en/plugins.html @@ -0,0 +1,2618 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<meta name="generator" content="AsciiDoc 8.6.8"> +<title>Kicad Plugins</title> +<style type="text/css"> +/* Shared CSS for AsciiDoc xhtml11 and html5 backends */ + +/* Default font. */ +body { + font-family: Georgia,serif; +} + +/* Title font. */ +h1, h2, h3, h4, h5, h6, +div.title, caption.title, +thead, p.table.header, +#toctitle, +#author, #revnumber, #revdate, #revremark, +#footer { + font-family: Arial,Helvetica,sans-serif; +} + +body { + margin: 1em 5% 1em 5%; +} + +a { + color: blue; + text-decoration: underline; +} +a:visited { + color: fuchsia; +} + +em { + font-style: italic; + color: navy; +} + +strong { + font-weight: bold; + color: #083194; +} + +h1, h2, h3, h4, h5, h6 { + color: #527bbd; + margin-top: 1.2em; + margin-bottom: 0.5em; + line-height: 1.3; +} + +h1, h2, h3 { + border-bottom: 2px solid silver; +} +h2 { + padding-top: 0.5em; +} +h3 { + float: left; +} +h3 + * { + clear: left; +} +h5 { + font-size: 1.0em; +} + +div.sectionbody { + margin-left: 0; +} + +hr { + border: 1px solid silver; +} + +p { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +ul, ol, li > p { + margin-top: 0; +} +ul > li { color: #aaa; } +ul > li > * { color: black; } + +pre { + padding: 0; + margin: 0; +} + +#author { + color: #527bbd; + font-weight: bold; + font-size: 1.1em; +} +#email { +} +#revnumber, #revdate, #revremark { +} + +#footer { + font-size: small; + border-top: 2px solid silver; + padding-top: 0.5em; + margin-top: 4.0em; +} +#footer-text { + float: left; + padding-bottom: 0.5em; +} +#footer-badges { + float: right; + padding-bottom: 0.5em; +} + +#preamble { + margin-top: 1.5em; + margin-bottom: 1.5em; +} +div.imageblock, div.exampleblock, div.verseblock, +div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, +div.admonitionblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.admonitionblock { + margin-top: 2.0em; + margin-bottom: 2.0em; + margin-right: 10%; + color: #606060; +} + +div.content { /* Block element content. */ + padding: 0; +} + +/* Block element titles. */ +div.title, caption.title { + color: #527bbd; + font-weight: bold; + text-align: left; + margin-top: 1.0em; + margin-bottom: 0.5em; +} +div.title + * { + margin-top: 0; +} + +td div.title:first-child { + margin-top: 0.0em; +} +div.content div.title:first-child { + margin-top: 0.0em; +} +div.content + div.title { + margin-top: 0.0em; +} + +div.sidebarblock > div.content { + background: #ffffee; + border: 1px solid #dddddd; + border-left: 4px solid #f0f0f0; + padding: 0.5em; +} + +div.listingblock > div.content { + border: 1px solid #dddddd; + border-left: 5px solid #f0f0f0; + background: #f8f8f8; + padding: 0.5em; +} + +div.quoteblock, div.verseblock { + padding-left: 1.0em; + margin-left: 1.0em; + margin-right: 10%; + border-left: 5px solid #f0f0f0; + color: #777777; +} + +div.quoteblock > div.attribution { + padding-top: 0.5em; + text-align: right; +} + +div.verseblock > pre.content { + font-family: inherit; + font-size: inherit; +} +div.verseblock > div.attribution { + padding-top: 0.75em; + text-align: left; +} +/* DEPRECATED: Pre version 8.2.7 verse style literal block. */ +div.verseblock + div.attribution { + text-align: left; +} + +div.admonitionblock .icon { + vertical-align: top; + font-size: 1.1em; + font-weight: bold; + text-decoration: underline; + color: #527bbd; + padding-right: 0.5em; +} +div.admonitionblock td.content { + padding-left: 0.5em; + border-left: 3px solid #dddddd; +} + +div.exampleblock > div.content { + border-left: 3px solid #dddddd; + padding-left: 0.5em; +} + +div.imageblock div.content { padding-left: 0; } +span.image img { border-style: none; } +a.image:visited { color: white; } + +dl { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +dt { + margin-top: 0.5em; + margin-bottom: 0; + font-style: normal; + color: navy; +} +dd > *:first-child { + margin-top: 0.1em; +} + +ul, ol { + list-style-position: outside; +} +ol.arabic { + list-style-type: decimal; +} +ol.loweralpha { + list-style-type: lower-alpha; +} +ol.upperalpha { + list-style-type: upper-alpha; +} +ol.lowerroman { + list-style-type: lower-roman; +} +ol.upperroman { + list-style-type: upper-roman; +} + +div.compact ul, div.compact ol, +div.compact p, div.compact p, +div.compact div, div.compact div { + margin-top: 0.1em; + margin-bottom: 0.1em; +} + +tfoot { + font-weight: bold; +} +td > div.verse { + white-space: pre; +} + +div.hdlist { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +div.hdlist tr { + padding-bottom: 15px; +} +dt.hdlist1.strong, td.hdlist1.strong { + font-weight: bold; +} +td.hdlist1 { + vertical-align: top; + font-style: normal; + padding-right: 0.8em; + color: navy; +} +td.hdlist2 { + vertical-align: top; +} +div.hdlist.compact tr { + margin: 0; + padding-bottom: 0; +} + +.comment { + background: yellow; +} + +.footnote, .footnoteref { + font-size: 0.8em; +} + +span.footnote, span.footnoteref { + vertical-align: super; +} + +#footnotes { + margin: 20px 0 20px 0; + padding: 7px 0 0 0; +} + +#footnotes div.footnote { + margin: 0 0 5px 0; +} + +#footnotes hr { + border: none; + border-top: 1px solid silver; + height: 1px; + text-align: left; + margin-left: 0; + width: 20%; + min-width: 100px; +} + +div.colist td { + padding-right: 0.5em; + padding-bottom: 0.3em; + vertical-align: top; +} +div.colist td img { + margin-top: 0.3em; +} + +@media print { + #footer-badges { display: none; } +} + +#toc { + margin-bottom: 2.5em; +} + +#toctitle { + color: #527bbd; + font-size: 1.1em; + font-weight: bold; + margin-top: 1.0em; + margin-bottom: 0.1em; +} + +div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { + margin-top: 0; + margin-bottom: 0; +} +div.toclevel2 { + margin-left: 2em; + font-size: 0.9em; +} +div.toclevel3 { + margin-left: 4em; + font-size: 0.9em; +} +div.toclevel4 { + margin-left: 6em; + font-size: 0.9em; +} + +span.aqua { color: aqua; } +span.black { color: black; } +span.blue { color: blue; } +span.fuchsia { color: fuchsia; } +span.gray { color: gray; } +span.green { color: green; } +span.lime { color: lime; } +span.maroon { color: maroon; } +span.navy { color: navy; } +span.olive { color: olive; } +span.purple { color: purple; } +span.red { color: red; } +span.silver { color: silver; } +span.teal { color: teal; } +span.white { color: white; } +span.yellow { color: yellow; } + +span.aqua-background { background: aqua; } +span.black-background { background: black; } +span.blue-background { background: blue; } +span.fuchsia-background { background: fuchsia; } +span.gray-background { background: gray; } +span.green-background { background: green; } +span.lime-background { background: lime; } +span.maroon-background { background: maroon; } +span.navy-background { background: navy; } +span.olive-background { background: olive; } +span.purple-background { background: purple; } +span.red-background { background: red; } +span.silver-background { background: silver; } +span.teal-background { background: teal; } +span.white-background { background: white; } +span.yellow-background { background: yellow; } + +span.big { font-size: 2em; } +span.small { font-size: 0.6em; } + +span.underline { text-decoration: underline; } +span.overline { text-decoration: overline; } +span.line-through { text-decoration: line-through; } + + +/* + * xhtml11 specific + * + * */ + +tt { + font-family: monospace; + font-size: inherit; + color: navy; +} + +div.tableblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.tableblock > table { + border: 3px solid #527bbd; +} +thead, p.table.header { + font-weight: bold; + color: #527bbd; +} +p.table { + margin-top: 0; +} +/* Because the table frame attribute is overriden by CSS in most browsers. */ +div.tableblock > table[frame="void"] { + border-style: none; +} +div.tableblock > table[frame="hsides"] { + border-left-style: none; + border-right-style: none; +} +div.tableblock > table[frame="vsides"] { + border-top-style: none; + border-bottom-style: none; +} + + +/* + * html5 specific + * + * */ + +.monospaced { + font-family: monospace; + font-size: inherit; + color: navy; +} + +table.tableblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +thead, p.tableblock.header { + font-weight: bold; + color: #527bbd; +} +p.tableblock { + margin-top: 0; +} +table.tableblock { + border-width: 3px; + border-spacing: 0px; + border-style: solid; + border-color: #527bbd; + border-collapse: collapse; +} +th.tableblock, td.tableblock { + border-width: 1px; + padding: 4px; + border-style: solid; + border-color: #527bbd; +} + +table.tableblock.frame-topbot { + border-left-style: hidden; + border-right-style: hidden; +} +table.tableblock.frame-sides { + border-top-style: hidden; + border-bottom-style: hidden; +} +table.tableblock.frame-none { + border-style: hidden; +} + +th.tableblock.halign-left, td.tableblock.halign-left { + text-align: left; +} +th.tableblock.halign-center, td.tableblock.halign-center { + text-align: center; +} +th.tableblock.halign-right, td.tableblock.halign-right { + text-align: right; +} + +th.tableblock.valign-top, td.tableblock.valign-top { + vertical-align: top; +} +th.tableblock.valign-middle, td.tableblock.valign-middle { + vertical-align: middle; +} +th.tableblock.valign-bottom, td.tableblock.valign-bottom { + vertical-align: bottom; +} + + +/* + * manpage specific + * + * */ + +body.manpage h1 { + padding-top: 0.5em; + padding-bottom: 0.5em; + border-top: 2px solid silver; + border-bottom: 2px solid silver; +} +body.manpage h2 { + border-style: none; +} +body.manpage div.sectionbody { + margin-left: 3em; +} + +@media print { + body.manpage div#toc { display: none; } +} + + +/* + * Theme specific overrides of the preceding (asciidoc.css) CSS. + * + */ +body { + font-family: Garamond, Georgia, serif; + font-size: 17px; + color: #3E4349; + line-height: 1.3em; +} +h1, h2, h3, h4, h5, h6, +div.title, caption.title, +thead, p.table.header, +#toctitle, +#author, #revnumber, #revdate, #revremark, +#footer { + font-family: Garmond, Georgia, serif; + font-weight: normal; + border-bottom-width: 0; + color: #3E4349; +} +div.title, caption.title { color: #596673; font-weight: bold; } +h1 { font-size: 240%; } +h2 { font-size: 180%; } +h3 { font-size: 150%; } +h4 { font-size: 130%; } +h5 { font-size: 115%; } +h6 { font-size: 100%; } +#header h1 { margin-top: 0; } +#toc { + color: #444444; + line-height: 1.5; + padding-top: 1.5em; +} +#toctitle { + font-size: 20px; +} +#toc a { + border-bottom: 1px dotted #999999; + color: #444444 !important; + text-decoration: none !important; +} +#toc a:hover { + border-bottom: 1px solid #6D4100; + color: #6D4100 !important; + text-decoration: none !important; +} +div.toclevel1 { margin-top: 0.2em; font-size: 16px; } +div.toclevel2 { margin-top: 0.15em; font-size: 14px; } +em, dt, td.hdlist1 { color: black; } +strong { color: #3E4349; } +a { color: #004B6B; text-decoration: none; border-bottom: 1px dotted #004B6B; } +a:visited { color: #615FA0; border-bottom: 1px dotted #615FA0; } +a:hover { color: #6D4100; border-bottom: 1px solid #6D4100; } +div.tableblock > table, table.tableblock { border: 3px solid #E8E8E8; } +th.tableblock, td.tableblock { border: 1px solid #E8E8E8; } +ul > li > * { color: #3E4349; } +pre, tt, .monospaced { font-family: Consolas,Menlo,'Deja Vu Sans Mono','Bitstream Vera Sans Mono',monospace; } +tt, .monospaced { font-size: 0.9em; color: black; +} +div.exampleblock > div.content, div.sidebarblock > div.content, div.listingblock > div.content { border-width: 0 0 0 3px; border-color: #E8E8E8; } +div.verseblock { border-left-width: 0; margin-left: 3em; } +div.quoteblock { border-left-width: 3px; margin-left: 0; margin-right: 0;} +div.admonitionblock td.content { border-left: 3px solid #E8E8E8; } + + +@media screen { + body { + max-width: 50em; /* approximately 80 characters wide */ + margin-left: 16em; + } + + #toc { + position: fixed; + top: 0; + left: 0; + bottom: 0; + width: 13em; + padding: 0.5em; + padding-bottom: 1.5em; + margin: 0; + overflow: auto; + border-right: 3px solid #f8f8f8; + background-color: white; + } + + #toc .toclevel1 { + margin-top: 0.5em; + } + + #toc .toclevel2 { + margin-top: 0.25em; + display: list-item; + color: #aaaaaa; + } + + #toctitle { + margin-top: 0.5em; + } +} +</style> +<script type="text/javascript"> +/*<+'])'); + // Function that scans the DOM tree for header elements (the DOM2 + // nodeIterator API would be a better technique but not supported by all + // browsers). + var iterate = function (el) { + for (var i = el.firstChild; i != null; i = i.nextSibling) { + if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { + var mo = re.exec(i.tagName); + if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") { + result[result.length] = new TocEntry(i, getText(i), mo[1]-1); + } + iterate(i); + } + } + } + iterate(el); + return result; + } + + var toc = document.getElementById("toc"); + if (!toc) { + return; + } + + // Delete existing TOC entries in case we're reloading the TOC. + var tocEntriesToRemove = []; + var i; + for (i = 0; i < toc.childNodes.length; i++) { + var entry = toc.childNodes[i]; + if (entry.nodeName.toLowerCase() == 'div' + && entry.getAttribute("class") + && entry.getAttribute("class").match(/^toclevel/)) + tocEntriesToRemove.push(entry); + } + for (i = 0; i < tocEntriesToRemove.length; i++) { + toc.removeChild(tocEntriesToRemove[i]); + } + + // Rebuild TOC entries. + var entries = tocEntries(document.getElementById("content"), toclevels); + for (var i = 0; i < entries.length; ++i) { + var entry = entries[i]; + if (entry.element.id == "") + entry.element.id = "_toc_" + i; + var a = document.createElement("a"); + a.href = "#" + entry.element.id; + a.appendChild(document.createTextNode(entry.text)); + var div = document.createElement("div"); + div.appendChild(a); + div.className = "toclevel" + entry.toclevel; + toc.appendChild(div); + } + if (entries.length == 0) + toc.parentNode.removeChild(toc); +}, + + +///////////////////////////////////////////////////////////////////// +// Footnotes generator +///////////////////////////////////////////////////////////////////// + +/* Based on footnote generation code from: + * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html + */ + +footnotes: function () { + // Delete existing footnote entries in case we're reloading the footnodes. + var i; + var noteholder = document.getElementById("footnotes"); + if (!noteholder) { + return; + } + var entriesToRemove = []; + for (i = 0; i < noteholder.childNodes.length; i++) { + var entry = noteholder.childNodes[i]; + if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote") + entriesToRemove.push(entry); + } + for (i = 0; i < entriesToRemove.length; i++) { + noteholder.removeChild(entriesToRemove[i]); + } + + // Rebuild footnote entries. + var cont = document.getElementById("content"); + var spans = cont.getElementsByTagName("span"); + var refs = {}; + var n = 0; + for (i=0; i<spans.length; i++) { + if (spans[i].className == "footnote") { + n++; + var note = spans[i].getAttribute("data-note"); + if (!note) { + // Use [\s\S] in place of . so multi-line matches work. + // Because JavaScript has no s (dotall) regex flag. + note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; + spans[i].innerHTML = + "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + spans[i].setAttribute("data-note", note); + } + noteholder.innerHTML += + "<div class='footnote' id='_footnote_" + n + "'>" + + "<a href='#_footnoteref_" + n + "' title='Return to text'>" + + n + "</a>. " + note + "</div>"; + var id =spans[i].getAttribute("id"); + if (id != null) refs["#"+id] = n; + } + } + if (n == 0) + noteholder.parentNode.removeChild(noteholder); + else { + // Process footnoterefs. + for (i=0; i<spans.length; i++) { + if (spans[i].className == "footnoteref") { + var href = spans[i].getElementsByTagName("a")[0].getAttribute("href"); + href = href.match(/#.*/)[0]; // Because IE return full URL. + n = refs[href]; + spans[i].innerHTML = + "[<a href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + } + } + } +}, + +install: function(toclevels) { + var timerId; + + function reinstall() { + asciidoc.footnotes(); + if (toclevels) { + asciidoc.toc(toclevels); + } + } + + function reinstallAndRemoveTimer() { + clearInterval(timerId); + reinstall(); + } + + timerId = setInterval(reinstall, 500); + if (document.addEventListener) + document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false); + else + window.onload = reinstallAndRemoveTimer; +} + +} +asciidoc.install(2); +/*]]>*/ +</script> +</head> +<body class="article"> +<div id="header"> +<h1>Kicad Plugins</h1> +<span id="author">The KiCad Team</span><br> +<div id="toc"> + <div id="toctitle">Table of Contents</div> + <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript> +</div> +</div> +<div id="content"> +<div id="preamble"> +<div class="sectionbody"> +<div class="paragraph"><p><em>KiCad Plugin System</em></p></div> +<div class="paragraph" id="copyright"><p><strong>Copyright</strong></p></div> +<div class="paragraph"><p>This document is Copyright © 2016 by it’s contributors as listed below. +You may distribute it and/or modify it under the terms of either the GNU +General Public License (<a href="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</a>), version 3 +or later, or the Creative Commons Attribution License +(<a href="http://creativecommons.org/licenses/by/3.0/">http://creativecommons.org/licenses/by/3.0/</a>), version 3.0 or later.</p></div> +<div class="paragraph"><p>All trademarks within this guide belong to their legitimate owners.</p></div> +<div class="paragraph" id="contributors"><p><strong>Contributors</strong></p></div> +<div class="paragraph"><p>Cirilo Bernardo</p></div> +<div class="paragraph" id="feedback"><p><strong>Feedback</strong></p></div> +<div class="paragraph"><p>Please direct any bug reports, suggestions or new versions to here:</p></div> +<div class="ulist"><ul> +<li> +<p> +About KiCad document: <a href="https://github.com/KiCad/kicad-doc/issues">https://github.com/KiCad/kicad-doc/issues</a> +</p> +</li> +<li> +<p> +About KiCad software: <a href="https://bugs.launchpad.net/kicad">https://bugs.launchpad.net/kicad</a> +</p> +</li> +<li> +<p> +About KiCad software i18n: <a href="https://github.com/KiCad/kicad-i18n/issues">https://github.com/KiCad/kicad-i18n/issues</a> +</p> +</li> +</ul></div> +<div class="paragraph" id="publication_date_and_software_version"><p><strong>Publication date and software version</strong></p></div> +<div class="paragraph"><p>Published on January 29, 2016.</p></div> +<div style="page-break-after:always"></div> +</div> +</div> +<div class="sect1"> +<h2 id="_introduction_to_the_kicad_plugin_system">1. Introduction to the KiCad plugin system</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The KiCad plugin system is a framework for extending the capabilities +of KiCad using shared libraries. One of the main advantages of using +a plugin is that it is not necessary to rebuild the KiCad suite while +developing a plugin; in fact plugins can be built with the aid of a +very small set of headers from the KiCad source tree. Removing the +requirement to build KiCad during plugin development greatly increases +productivity by ensuring that the developer only compiles code directly +related to the plugin which is being developed and thus reducing the +time required for each build and test cycle.</p></div> +<div class="paragraph"><p>Plugins were initially developed for the 3D model viewer to make it +possible to support more types of 3D models without requiring major +changes to the KiCad source for each new model supported. The plugin +framework was later generalized so that in the future developers can +create different classes of plugins. Currently only 3D plugins are +implemented within KiCad but it is envisioned that a PCB plugin will +eventually be developed to make it possible for users to implement +data Importers and Exporters.</p></div> +<div class="sect2"> +<h3 id="REF:PLUGIN_CLASSES">1.1. Plugin Classes</h3> +<div class="paragraph"><p>Plugins are divided into Plugin Classes since each plugin addresses +problems in a specific domain and therefore requires an interface +unique to that domain. For example, the 3D model plugins load 3D +model data from files and translate that data into a format which +can be displayed by the 3D viewer while a PCB Import/Export plugin +would take PCB data and export to other electronics or mechanical +data formats or translate a foreign format into a KiCad PCB. At +the moment only the 3D Plugin Class has been developed and this +will be the focus of this document.</p></div> +<div class="paragraph"><p>Implementing a Plugin Class requires creating code within the KiCad +source tree which manages the loading of plugin code. Within the +KiCad source tree, the file plugins/ldr/pluginldr.h declares the +base class for all plugin loaders. This class declares the most +basic functions which we would expect to find in any KiCad plugin +(boilerplate code) and its implementation provides basic checks +on version compatibility between the plugin loader and the +available plugins. The header plugins/ldr/3d/pluginldr3D.h declares +a loader for the 3D Plugin Class. The loader is responsible for +loading a given plugin and making its functions available to KiCad. +Each instance of a plugin loader represents an actual plugin +implementation and acts as a transparent bridge between kicad and +the plugin’s features. The loader is not the only code required within +KiCad to support plugins; we also need code to discover the plugins +and code to invoke the functions of the plugins via the plugin loader. +In the case of the 3D plugins the discovery and invocation functions +are all contained within the S3D_CACHE class.</p></div> +<div class="paragraph"><p>Plugin developers do not need to be concerned with the details of +KiCad’s internal code for managing plugins unless a new Plugin +Class is being developed; a plugin only needs to define the functions +declared by their specific plugin class.</p></div> +<div class="paragraph"><p>The header include/plugins/kicad_plugin.h declares the generic +functions required of all KiCad plugins; these functions identify +the Plugin Class, provide the name of the specific plugin, provide +version information for the Plugin Class API, provide version +information for the specific plugin, and provides a basic version +compatibility check on the Plugin Class API. In brief, these +functions are:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/* Return a UTF-8 string naming the Plugin Class */</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginClass</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Return version information for the Plugin Class API */</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetClassVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Return true if the version check implemented in the plugin</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> determines that the given Plugin Class API is compatible.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CheckClassVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Major<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Minor<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Revision <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Return the name of the specific plugin, for example "PLUGIN_3D_VRML" */</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginName</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Return version information for the specific plugin */</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPluginVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">);</span></tt></pre></div></div> +<div class="sect3"> +<h4 id="REF:CLASS_PLUGIN_3D">1.1.1. Plugin Class: PLUGIN_3D</h4> +<div class="paragraph"><p>The header include/plugins/3d/3d_plugin.h declares the functions +which must be implemented by all 3D plugins and defines a number of +functions which are required by the plugin and which the user must +not reimplement. The defined functions which the user must not +reimplement are:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/* Returns the Plugin Class name "PLUGIN_3D" */</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginClass</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Return version information for the PLUGIN_3D API */</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetClassVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Performs basic version checks enforced by the developers of</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> the loader for the PLUGIN_3D class and returns true if the</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> checks pass</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CheckClassVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Revision <span style="color: #990000">);</span></tt></pre></div></div> +<div class="paragraph"><p>The functions which the user must implement are as follows:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/* Return the number of extension strings supported by the plugin */</span></span> +<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">GetNExtensions</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Return the requested extension string; valid values are 0 to</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> GetNExtensions() - 1</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetModelExtension</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Return the total number of file filters supported by the plugin */</span></span> +<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">GetNFilters</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Return the file filter requested; valid values are 0 to</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> GetNFilters() - 1</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetFileFilter</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Return true if the plugin can render this type of 3D model.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> In some cases a plugin may not yet provide a visual model</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> and must return false.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CanRender</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Load the specified model and return a pointer to its visual model data */</span></span> +SCENEGRAPH<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">Load</span></span><span style="color: #990000">(</span> <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> aFileName <span style="color: #990000">);</span></tt></pre></div></div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_tutorials_3d_plugin_class">2. Tutorials: 3D Plugin Class</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section contains a description of two very simple plugins of the +PLUGIN_3D class and walks the user through the setup and building of +the code.</p></div> +<div class="sect2"> +<h3 id="_tutorial_3d_plugin_demo_1">2.1. Tutorial: 3D Plugin, Demo 1</h3> +<div class="paragraph"><p>This tutorial walks the user through the development of a very basic +3D plugin named “PLUGIN_3D_DEMO1”. The purpose of the tutorial is +to demonstrate the construction of a very basic 3D plugin which does +nothing other than provide a few filter strings which permit the +KiCad user to filter file names while browsing for 3D models. The +code demonstrated here is the absolute minimum requirement for any +3D plugin and can be used as a template for creating more functional +plugins.</p></div> +<div class="paragraph"><p>In order to build the demo project we require the following:</p></div> +<div class="ulist"><ul> +<li> +<p> +CMake +</p> +</li> +<li> +<p> +KiCad plugin headers +</p> +</li> +<li> +<p> +KiCad Scene Graph library, kicad_3dsg +</p> +</li> +</ul></div> +<div class="paragraph"><p>To automatically detect the KiCad headers and library we shall use a +CMake FindPackage script; the script supplied in this tutorial should +work on Linux and MSWindows if the relevant header files are installed +to <span class="monospaced">${KICAD_ROOT_DIR}/kicad</span> and the KiCad Scene Graph library is +installed in <span class="monospaced">${KICAD_ROOT_DIR}/lib</span>.</p></div> +<div class="paragraph"><p>To start let’s create a project directory and the FindPackage script:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>mkdir demo <span style="color: #990000">&&</span> cd demo +<span style="font-weight: bold"><span style="color: #0000FF">export</span></span> <span style="color: #009900">DEMO_ROOT</span><span style="color: #990000">=</span><span style="color: #009900">${PWD}</span> +mkdir CMakeModules <span style="color: #990000">&&</span> cd CMakeModules +cat <span style="color: #990000">></span> FindKICAD<span style="color: #990000">.</span>cmake <span style="color: #990000"><<</span> _EOF +find_path<span style="color: #990000">(</span> KICAD_INCLUDE_DIR kicad/plugins/kicad_plugin<span style="color: #990000">.</span>h + PATHS <span style="color: #009900">${KICAD_ROOT_DIR}</span>/include <span style="color: #009900">$ENV</span>{KICAD_ROOT_DIR}/include + DOC <span style="color: #FF0000">"Kicad plugins header path."</span> + <span style="color: #990000">)</span> + +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT <span style="color: #009900">${KICAD_INCLUDE_DIR}</span> STREQUAL <span style="color: #FF0000">"KICAD_INCLUDE_DIR-NOTFOUND"</span> <span style="color: #990000">)</span> + + <span style="font-style: italic"><span style="color: #9A1900"># attempt to extract the version information from sg_version.h</span></span> + find_file<span style="color: #990000">(</span> KICAD_SGVERSION sg_version<span style="color: #990000">.</span>h + PATHS <span style="color: #009900">${KICAD_INCLUDE_DIR}</span> + PATH_SUFFIXES kicad/plugins<span style="color: #990000">/</span>3dapi + NO_DEFAULT_PATH <span style="color: #990000">)</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT <span style="color: #009900">${KICAD_SGVERSION}</span> STREQUAL <span style="color: #FF0000">"KICAD_SGVERSION-NOTFOUND"</span> <span style="color: #990000">)</span> + + <span style="font-style: italic"><span style="color: #9A1900"># extract the "#define KICADSG_VERSION*" lines</span></span> + file<span style="color: #990000">(</span> STRINGS <span style="color: #009900">${KICAD_SGVERSION}</span> _version REGEX <span style="color: #FF0000">"^#define.*KICADSG_VERSION.*"</span> <span style="color: #990000">)</span> + + foreach<span style="color: #990000">(</span> SVAR <span style="color: #009900">${_version}</span> <span style="color: #990000">)</span> + string<span style="color: #990000">(</span> REGEX MATCH KICADSG_VERSION_<span style="color: #990000">[</span>M<span style="color: #990000">,</span>A<span style="color: #990000">,</span>J<span style="color: #990000">,</span>O<span style="color: #990000">,</span>R<span style="color: #990000">,</span>I<span style="color: #990000">,</span>N<span style="color: #990000">,</span>P<span style="color: #990000">,</span>T<span style="color: #990000">,</span>C<span style="color: #990000">,</span>H<span style="color: #990000">,</span>E<span style="color: #990000">,</span>V<span style="color: #990000">,</span>I<span style="color: #990000">,</span>S<span style="color: #990000">]*</span> _VARNAME <span style="color: #009900">${SVAR}</span> <span style="color: #990000">)</span> + string<span style="color: #990000">(</span> REGEX MATCH <span style="color: #990000">[</span><span style="color: #993399">0</span>-<span style="color: #993399">9</span><span style="color: #990000">]+</span> _VALUE <span style="color: #009900">${SVAR}</span> <span style="color: #990000">)</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT <span style="color: #009900">${_VARNAME}</span> STREQUAL <span style="color: #FF0000">""</span> AND NOT <span style="color: #009900">${_VALUE}</span> STREQUAL <span style="color: #FF0000">""</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> _<span style="color: #009900">${_VARNAME}</span> <span style="color: #009900">${_VALUE}</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #000000">endif()</span></span> + + <span style="font-weight: bold"><span style="color: #000000">endforeach()</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">#ensure that NOT SG3D_VERSION* will evaluate to '0'</span></span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT _KICADSG_VERSION_MAJOR <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> _KICADSG_VERSION_MAJOR <span style="color: #993399">0</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #000000">endif()</span></span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT _KICADSG_VERSION_MINOR <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> _KICADSG_VERSION_MINOR <span style="color: #993399">0</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #000000">endif()</span></span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT _KICADSG_VERSION_PATCH <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> _KICADSG_VERSION_PATCH <span style="color: #993399">0</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #000000">endif()</span></span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> NOT _KICADSG_VERSION_REVISION <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> _KICADSG_VERSION_REVISION <span style="color: #993399">0</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #000000">endif()</span></span> + + <span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> KICAD_VERSION <span style="color: #009900">${_KICADSG_VERSION_MAJOR}.${_KICADSG_VERSION_MINOR}.${_KICADSG_VERSION_PATCH}.${_KICADSG_VERSION_REVISION}</span> <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">unset</span></span><span style="color: #990000">(</span> KICAD_SGVERSION CACHE <span style="color: #990000">)</span> + + <span style="font-weight: bold"><span style="color: #000000">endif()</span></span> +<span style="font-weight: bold"><span style="color: #000000">endif()</span></span> + + +find_library<span style="color: #990000">(</span> KICAD_LIBRARY + NAMES kicad_3dsg + PATHS + <span style="color: #009900">${KICAD_ROOT_DIR}</span>/lib <span style="color: #009900">$ENV</span>{KICAD_ROOT_DIR}/lib + <span style="color: #009900">${KICAD_ROOT_DIR}</span>/bin <span style="color: #009900">$ENV</span>{KICAD_ROOT_DIR}/bin + DOC <span style="color: #FF0000">"Kicad scenegraph library path."</span> + <span style="color: #990000">)</span> + +include<span style="color: #990000">(</span> FindPackageHandleStandardArgs <span style="color: #990000">)</span> +FIND_PACKAGE_HANDLE_STANDARD_ARGS<span style="color: #990000">(</span> KICAD + REQUIRED_VARS + KICAD_INCLUDE_DIR + KICAD_LIBRARY + KICAD_VERSION + VERSION_VAR KICAD_VERSION <span style="color: #990000">)</span> + + +mark_as_advanced<span style="color: #990000">(</span> KICAD_INCLUDE_DIR <span style="color: #990000">)</span> +<span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> KICAD_VERSION_MAJOR <span style="color: #009900">${_KICADSG_VERSION_MAJOR}</span> CACHE INTERNAL <span style="color: #FF0000">""</span> <span style="color: #990000">)</span> +<span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> KICAD_VERSION_MINOR <span style="color: #009900">${_KICADSG_VERSION_MINOR}</span> CACHE INTERNAL <span style="color: #FF0000">""</span> <span style="color: #990000">)</span> +<span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> KICAD_VERSION_PATCH <span style="color: #009900">${_KICADSG_VERSION_PATCH}</span> CACHE INTERNAL <span style="color: #FF0000">""</span> <span style="color: #990000">)</span> +<span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> KICAD_VERSION_TWEAK <span style="color: #009900">${_KICADSG_VERSION_REVISION}</span> CACHE INTERNAL <span style="color: #FF0000">""</span> <span style="color: #990000">)</span> +_EOF</tt></pre></div></div> +<div class="paragraph"><p>Kicad and its plugin headers must be installed; if they are installed +to a user directory or under <span class="monospaced">/opt</span> on Linux, or you are using Windows, +you will need to set the <span class="monospaced">KICAD_ROOT_DIR</span> environment variable to +point to the directory containing the kicad <span class="monospaced">include</span> and <span class="monospaced">lib</span> +directories. For OSX the FindPackage script presented here may require +some adjustments.</p></div> +<div class="paragraph"><p>To configure and build the tutorial code we will use CMake and +create a CMakeLists.txt script file:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>cd <span style="color: #009900">${DEMO_ROOT}</span> +cat <span style="color: #990000">></span> CMakeLists<span style="color: #990000">.</span>txt <span style="color: #990000"><<</span> _EOF +<span style="font-style: italic"><span style="color: #9A1900"># declare the name of the project</span></span> +project<span style="color: #990000">(</span> PLUGIN_DEMO <span style="color: #990000">)</span> + +<span style="font-style: italic"><span style="color: #9A1900"># check that we have a version of CMake with all required features</span></span> +cmake_minimum_required<span style="color: #990000">(</span> VERSION <span style="color: #993399">2.8</span><span style="color: #990000">.</span><span style="color: #993399">12</span> FATAL_ERROR <span style="color: #990000">)</span> + +<span style="font-style: italic"><span style="color: #9A1900"># inform CMake of where to find the FindKICAD script</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">set</span></span><span style="color: #990000">(</span> CMAKE_MODULE_PATH <span style="color: #009900">${PROJECT_SOURCE_DIR}</span>/CMakeModules <span style="color: #990000">)</span> + +<span style="font-style: italic"><span style="color: #9A1900"># attempt to discover the installed kicad headers and library</span></span> +<span style="font-style: italic"><span style="color: #9A1900"># and set the variables:</span></span> +<span style="font-style: italic"><span style="color: #9A1900"># KICAD_INCLUDE_DIR</span></span> +<span style="font-style: italic"><span style="color: #9A1900"># KICAD_LIBRARY</span></span> +find_package<span style="color: #990000">(</span> KICAD <span style="color: #993399">1.0</span> REQUIRED <span style="color: #990000">)</span> + +<span style="font-style: italic"><span style="color: #9A1900"># add the kicad include directory to the compiler's search path</span></span> +include_directories<span style="color: #990000">(</span> <span style="color: #009900">${KICAD_INCLUDE_DIR}</span>/kicad <span style="color: #990000">)</span> + +<span style="font-style: italic"><span style="color: #9A1900"># create a plugin named s3d_plugin_demo1</span></span> +add_library<span style="color: #990000">(</span> s3d_plugin_demo1 MODULE + src/s3d_plugin_demo1<span style="color: #990000">.</span>cpp + <span style="color: #990000">)</span> + +_EOF</tt></pre></div></div> +<div class="paragraph"><p>The first demo project is very basic; it consists of a single file +with no external link dependencies other than the compiler defaults. +We start by creating a source directory:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>cd <span style="color: #009900">${DEMO_ROOT}</span> +mkdir src <span style="color: #990000">&&</span> cd src +<span style="font-weight: bold"><span style="color: #0000FF">export</span></span> <span style="color: #009900">DEMO_SRC</span><span style="color: #990000">=</span><span style="color: #009900">${PWD}</span></tt></pre></div></div> +<div class="paragraph"><p>Now we create the plugin source itself:</p></div> +<div class="listingblock"> +<div class="title">s3d_plugin_demo1.cpp</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000"><iostream></span> + +<span style="font-style: italic"><span style="color: #9A1900">// the 3d_plugin.h header defines the functions required of 3D plugins</span></span> +<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">"plugins/3d/3d_plugin.h"</span> + +<span style="font-style: italic"><span style="color: #9A1900">// define the version information of this plugin; do not confuse this</span></span> +<span style="font-style: italic"><span style="color: #9A1900">// with the Plugin Class version which is defined in 3d_plugin.h</span></span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO1_MAJOR <span style="color: #993399">1</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO1_MINOR <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO1_PATCH <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO1_REVNO <span style="color: #993399">0</span> + +<span style="font-style: italic"><span style="color: #9A1900">// implement the function which provides users with this plugin's name</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginName</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #FF0000">"PLUGIN_3D_DEMO1"</span><span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// implement the function which provides users with this plugin's version</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPluginVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Major <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Major <span style="color: #990000">=</span> PLUGIN_3D_DEMO1_MAJOR<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Minor <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Minor <span style="color: #990000">=</span> PLUGIN_3D_DEMO1_MINOR<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Patch <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Patch <span style="color: #990000">=</span> PLUGIN_3D_DEMO1_PATCH<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Revision <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Revision <span style="color: #990000">=</span> PLUGIN_3D_DEMO1_REVNO<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span><span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// number of extensions supported; on *NIX systems the extensions are</span></span> +<span style="font-style: italic"><span style="color: #9A1900">// provided twice - once in lower case and once in upper case letters</span></span> +<span style="font-weight: bold"><span style="color: #000080">#ifdef</span></span> _WIN32 +<span style="font-weight: bold"><span style="color: #000080"> #define</span></span> NEXTS <span style="color: #993399">7</span> +<span style="font-weight: bold"><span style="color: #000080">#else</span></span> +<span style="font-weight: bold"><span style="color: #000080"> #define</span></span> NEXTS <span style="color: #993399">14</span> +<span style="font-weight: bold"><span style="color: #000080">#endif</span></span> + +<span style="font-style: italic"><span style="color: #9A1900">// number of filter sets supported</span></span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> NFILS <span style="color: #993399">5</span> + +<span style="font-style: italic"><span style="color: #9A1900">// define the extension strings and filter strings which this</span></span> +<span style="font-style: italic"><span style="color: #9A1900">// plugin will supply to the user</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext0<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"wrl"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext1<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"x3d"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext2<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"emn"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext3<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"iges"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext4<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"igs"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext5<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"stp"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext6<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"step"</span><span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #000080">#ifdef</span></span> _WIN32 +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil0<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"VRML 1.0/2.0 (*.wrl)|*.wrl"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil1<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"X3D (*.x3d)|*.x3d"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil2<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"IDF 2.0/3.0 (*.emn)|*.emn"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil3<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"IGESv5.3 (*.igs;*.iges)|*.igs;*.iges"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil4<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"STEP (*.stp;*.step)|*.stp;*.step"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #000080">#else</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext7<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"WRL"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext8<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"X3D"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext9<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"EMN"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext10<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"IGES"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext11<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"IGS"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext12<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"STP"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext13<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"STEP"</span><span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil0<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"VRML 1.0/2.0 (*.wrl;*.WRL)|*.wrl;*.WRL"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil1<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"X3D (*.x3d;*.X3D)|*.x3d;*.X3D"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil2<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"IDF 2.0/3.0 (*.emn;*.EMN)|*.emn;*.EMN"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil3<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"IGESv5.3 (*.igs;*.iges;*.IGS;*.IGES)|*.igs;*.iges;*.IGS;*.IGES"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil4<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"STEP (*.stp;*.step;*.STP;*.STEP)|*.stp;*.step;*.STP;*.STEP"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #000080">#endif</span></span> + +<span style="font-style: italic"><span style="color: #9A1900">// instantiate a convenient data structure for accessing the</span></span> +<span style="font-style: italic"><span style="color: #9A1900">// lists of extension and filter strings</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="font-weight: bold"><span style="color: #0000FF">struct</span></span> <span style="color: #008080">FILE_DATA</span> +<span style="color: #FF0000">{</span> + <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> extensions<span style="color: #990000">[</span>NEXTS<span style="color: #990000">];</span> + <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> filters<span style="color: #990000">[</span>NFILS<span style="color: #990000">];</span> + + <span style="font-weight: bold"><span style="color: #000000">FILE_DATA</span></span><span style="color: #990000">()</span> + <span style="color: #FF0000">{</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext0<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext1<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext2<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext3<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext4<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">5</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext5<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">6</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext6<span style="color: #990000">;</span> + filters<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> fil0<span style="color: #990000">;</span> + filters<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> fil1<span style="color: #990000">;</span> + filters<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> fil2<span style="color: #990000">;</span> + filters<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> fil3<span style="color: #990000">;</span> + filters<span style="color: #990000">[</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> fil4<span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #000080">#ifndef</span></span> _WIN32 + extensions<span style="color: #990000">[</span><span style="color: #993399">7</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext7<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">8</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext8<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">9</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext9<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext10<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">11</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext11<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">12</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext12<span style="color: #990000">;</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">13</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext13<span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #000080">#endif</span></span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span><span style="color: #990000">;</span> + <span style="color: #FF0000">}</span> + +<span style="color: #FF0000">}</span> file_data<span style="color: #990000">;</span> + + +<span style="font-style: italic"><span style="color: #9A1900">// return the number of extensions supported by this plugin</span></span> +<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">GetNExtensions</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NEXTS<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// return the indexed extension string</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetModelExtension</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> aIndex <span style="color: #990000"><</span> <span style="color: #993399">0</span> <span style="color: #990000">||</span> aIndex <span style="color: #990000">>=</span> NEXTS <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NULL<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> file_data<span style="color: #990000">.</span>extensions<span style="color: #990000">[</span>aIndex<span style="color: #990000">];</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// return the number of filter strings provided by this plugin</span></span> +<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">GetNFilters</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NFILS<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// return the indexed filter string</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetFileFilter</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> aIndex <span style="color: #990000"><</span> <span style="color: #993399">0</span> <span style="color: #990000">||</span> aIndex <span style="color: #990000">>=</span> NFILS <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NULL<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> file_data<span style="color: #990000">.</span>filters<span style="color: #990000">[</span>aIndex<span style="color: #990000">];</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// return false since this plugin does not provide visualization data</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CanRender</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> false<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// return NULL since this plugin does not provide visualization data</span></span> +SCENEGRAPH<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">Load</span></span><span style="color: #990000">(</span> <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> aFileName <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-style: italic"><span style="color: #9A1900">// this dummy plugin does not support rendering of any models</span></span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NULL<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span></tt></pre></div></div> +<div class="paragraph"><p>This source file meets all the minimum requirements to implement +a 3D plugin. The plugin does not produce any data for rendering +models but it can provide KiCad with a list of supported model +file extensions and file extension filters to enhance the 3D +model file selection dialog. Within KiCad the extension strings +are used to select the plugins which may be used to load a +specified model; for example if the plugin is <span class="monospaced">wrl</span> then KiCad +will invoke each plugin which claims to support the extension +<span class="monospaced">wrl</span> in turn until a plugin returns visualization data. The +file filters provided by each plugin are passed onto the 3D +file selector dialogs to improve the browsing UI.</p></div> +<div class="paragraph"><p>To build the plugin:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>cd <span style="color: #009900">${DEMO_ROOT}</span> +<span style="font-style: italic"><span style="color: #9A1900"># export KICAD_ROOT_DIR if necessary</span></span> +mkdir build <span style="color: #990000">&&</span> cd build +cmake <span style="color: #990000">..</span> <span style="color: #990000">&&</span> make</tt></pre></div></div> +<div class="paragraph"><p>The plugin will be built but not installed; you may copy the +plugin to the same directory in which the kicad installation +has its plugins if you wish to load the plugin.</p></div> +</div> +<div class="sect2"> +<h3 id="_tutorial_3d_plugin_demo_2">2.2. Tutorial: 3D Plugin, Demo 2</h3> +<div class="paragraph"><p>This tutorial walks the user through the development of a 3D plugin +named “PLUGIN_3D_DEMO2”. The purpose of the tutorial is to demonstrate +the construction of a very basic scene graph which the kicad previewer +can render. The plugin claims to handle files of type <span class="monospaced">txt</span>. Although +the file must exist in order for the cache manager to invoke the +plugin, the file contents are not processed by this plugin; instead, +the plugin simply creates a scene graph containing a pair of tetrahedra. +This tutorial assumes that the first tutorial had been completed and +that the CMakeLists.txt and FindKICAD.cmake script files have been +created.</p></div> +<div class="paragraph"><p>The new source file shall be placed in the same directory as the +previous tutorial’s source file and we shall extend the previous +tutorial’s CMakeLists.txt file to build this tutorial. Since this +plugin will create a scene graph for KiCad we need to link to +KiCad’s scene graph library <span class="monospaced">kicad_3dsg</span>. KiCad’s Scene Graph +Library provides a set of classes which can be used to build the +Scene Graph Object; the Scene Graph Object is an intermediate +data visualization format used by the 3D Cache Manager. All plugins +which support model visualization must translate the model data into +a scene graph via this library.</p></div> +<div class="paragraph"><p>First step: extend CMakeLists.txt to build this tutorial project:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>cd <span style="color: #009900">${DEMO_ROOT}</span> +cat <span style="color: #990000">>></span> CMakeLists<span style="color: #990000">.</span>txt <span style="color: #990000"><<</span> _EOF +add_library<span style="color: #990000">(</span> s3d_plugin_demo2 MODULE + src/s3d_plugin_demo2<span style="color: #990000">.</span>cpp + <span style="color: #990000">)</span> + +target_link_libraries<span style="color: #990000">(</span> s3d_plugin_demo2 <span style="color: #009900">${KICAD_LIBRARY}</span> <span style="color: #990000">)</span> +_EOF</tt></pre></div></div> +<div class="paragraph"><p>Now we change to the source directory and create the source file:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>cd <span style="color: #009900">${DEMO_SRC}</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">s3d_plugin_demo2.cpp</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000"><cmath></span> +<span style="font-style: italic"><span style="color: #9A1900">// 3D Plugin Class declarations</span></span> +<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">"plugins/3d/3d_plugin.h"</span> +<span style="font-style: italic"><span style="color: #9A1900">// interface to KiCad Scene Graph Library</span></span> +<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">"plugins/3dapi/ifsg_all.h"</span> + +<span style="font-style: italic"><span style="color: #9A1900">// version information for this plugin</span></span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO2_MAJOR <span style="color: #993399">1</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO2_MINOR <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO2_PATCH <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> PLUGIN_3D_DEMO2_REVNO <span style="color: #993399">0</span> + +<span style="font-style: italic"><span style="color: #9A1900">// provide the name of this plugin</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginName</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #FF0000">"PLUGIN_3D_DEMO2"</span><span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + +<span style="font-style: italic"><span style="color: #9A1900">// provide the version of this plugin</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPluginVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Major <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Major <span style="color: #990000">=</span> PLUGIN_3D_DEMO2_MAJOR<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Minor <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Minor <span style="color: #990000">=</span> PLUGIN_3D_DEMO2_MINOR<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Patch <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Patch <span style="color: #990000">=</span> PLUGIN_3D_DEMO2_PATCH<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> Revision <span style="color: #990000">)</span> + <span style="color: #990000">*</span>Revision <span style="color: #990000">=</span> PLUGIN_3D_DEMO2_REVNO<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span><span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + + +<span style="font-style: italic"><span style="color: #9A1900">// number of extensions supported</span></span> +<span style="font-weight: bold"><span style="color: #000080">#ifdef</span></span> _WIN32 +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> NEXTS <span style="color: #993399">1</span> +<span style="font-weight: bold"><span style="color: #000080">#else</span></span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> NEXTS <span style="color: #993399">2</span> +<span style="font-weight: bold"><span style="color: #000080">#endif</span></span> + +<span style="font-style: italic"><span style="color: #9A1900">// number of filter sets supported</span></span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> NFILS <span style="color: #993399">1</span> + +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext0<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"txt"</span><span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #000080">#ifdef</span></span> _WIN32 +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil0<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"demo (*.txt)|*.txt"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #000080">#else</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> ext1<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"TXT"</span><span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="color: #009900">char</span> fil0<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"demo (*.txt;*.TXT)|*.txt;*.TXT"</span><span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #000080">#endif</span></span> + + +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="font-weight: bold"><span style="color: #0000FF">struct</span></span> <span style="color: #008080">FILE_DATA</span> +<span style="color: #FF0000">{</span> + <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> extensions<span style="color: #990000">[</span>NEXTS<span style="color: #990000">];</span> + <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> filters<span style="color: #990000">[</span>NFILS<span style="color: #990000">];</span> + + <span style="font-weight: bold"><span style="color: #000000">FILE_DATA</span></span><span style="color: #990000">()</span> + <span style="color: #FF0000">{</span> + extensions<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext0<span style="color: #990000">;</span> + filters<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> fil0<span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #000080">#ifndef</span></span> _WIN32 + extensions<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> ext1<span style="color: #990000">;</span> +<span style="font-weight: bold"><span style="color: #000080">#endif</span></span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span><span style="color: #990000">;</span> + <span style="color: #FF0000">}</span> + +<span style="color: #FF0000">}</span> file_data<span style="color: #990000">;</span> + + +<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">GetNExtensions</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NEXTS<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + + +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetModelExtension</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> aIndex <span style="color: #990000"><</span> <span style="color: #993399">0</span> <span style="color: #990000">||</span> aIndex <span style="color: #990000">>=</span> NEXTS <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NULL<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> file_data<span style="color: #990000">.</span>extensions<span style="color: #990000">[</span>aIndex<span style="color: #990000">];</span> +<span style="color: #FF0000">}</span> + + +<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">GetNFilters</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NFILS<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + + +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetFileFilter</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span><span style="color: #990000">(</span> aIndex <span style="color: #990000"><</span> <span style="color: #993399">0</span> <span style="color: #990000">||</span> aIndex <span style="color: #990000">>=</span> NFILS <span style="color: #990000">)</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> NULL<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> file_data<span style="color: #990000">.</span>filters<span style="color: #990000">[</span>aIndex<span style="color: #990000">];</span> +<span style="color: #FF0000">}</span> + + +<span style="font-style: italic"><span style="color: #9A1900">// return true since this plugin can provide visualization data</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CanRender</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> true<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span> + + +<span style="font-style: italic"><span style="color: #9A1900">// create the visualization data</span></span> +SCENEGRAPH<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">Load</span></span><span style="color: #990000">(</span> <span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> aFileName <span style="color: #990000">)</span> +<span style="color: #FF0000">{</span> + <span style="font-style: italic"><span style="color: #9A1900">// For this demonstration we create a tetrahedron (tx1) consisting</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// of a SCENEGRAPH (VRML Transform) which in turn contains 4</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// SGSHAPE (VRML Shape) objects representing each of the sides of</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// the tetrahedron. Each Shape is associated with a color (SGAPPEARANCE)</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// and a SGFACESET (VRML Geometry->indexedFaceSet). Each SGFACESET is</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// associated with a vertex list (SGCOORDS), a per-vertex normals</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// list (SGNORMALS), and a coordinate index (SGCOORDINDEX). One shape</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// is used to represent each face so that we may use per-vertex-per-face</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// normals.</span></span> + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// The tetrahedron in turn is a child of a top level SCENEGRAPH (tx0)</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// which has a second SCENEGRAPH child (tx2) which is a transformation</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// of the tetrahedron tx1 (rotation + translation). This demonstrates</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// the reuse of components within the scene graph hierarchy.</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">// define the vertices of the tetrahedron</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// face 1: 0, 3, 1</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// face 2: 0, 2, 3</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// face 3: 1, 3, 2</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// face 4: 0, 1, 2</span></span> + <span style="color: #009900">double</span> SQ2 <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">sqrt</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.5</span> <span style="color: #990000">);</span> + <span style="color: #008080">SGPOINT</span> vert<span style="color: #990000">[</span><span style="color: #993399">4</span><span style="color: #990000">];</span> + vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">(</span> <span style="color: #993399">1.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #990000">-</span>SQ2 <span style="color: #990000">);</span> + vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">(</span> <span style="color: #990000">-</span><span style="color: #993399">1.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #990000">-</span>SQ2 <span style="color: #990000">);</span> + vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">1.0</span><span style="color: #990000">,</span> SQ2 <span style="color: #990000">);</span> + vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #990000">-</span><span style="color: #993399">1.0</span><span style="color: #990000">,</span> SQ2 <span style="color: #990000">);</span> + + + <span style="font-style: italic"><span style="color: #9A1900">// create the top level transform; this will hold all other</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// scenegraph objects; a transform may hold other transforms and</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// shapes</span></span> + IFSG_TRANSFORM<span style="color: #990000">*</span> tx0 <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_TRANSFORM</span></span><span style="color: #990000">(</span> true <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// create the transform which will house the shapes</span></span> + IFSG_TRANSFORM<span style="color: #990000">*</span> tx1 <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_TRANSFORM</span></span><span style="color: #990000">(</span> tx0<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">GetRawPtr</span></span><span style="color: #990000">()</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// add a shape which we will use to define one face of the tetrahedron;</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// shapes hold facesets and appearances</span></span> + IFSG_SHAPE<span style="color: #990000">*</span> shape <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_SHAPE</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>tx1 <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// add a faceset; these contain coordinate lists, coordinate indices,</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// vertex lists, vertex indices, and may also contain color lists and</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// their indices.</span></span> + + IFSG_FACESET<span style="color: #990000">*</span> face <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_FACESET</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + + IFSG_COORDS<span style="color: #990000">*</span> cp <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDS</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// coordinate indices - note: enforce triangles;</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// in real plugins where it is not necessarily possible</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// to determine which side a triangle is visible from,</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 2 point orders must be specified for each triangle</span></span> + IFSG_COORDINDEX<span style="color: #990000">*</span> coordIdx <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDINDEX</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">0</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">1</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">2</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// create an appearance; appearances are owned by shapes</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">// magenta</span></span> + IFSG_APPEARANCE<span style="color: #990000">*</span> material <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_APPEARANCE</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape<span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.1</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.1</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.8</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.8</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetShininess</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.2</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// normals</span></span> + IFSG_NORMALS<span style="color: #990000">*</span> np <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_NORMALS</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + <span style="color: #008080">SGVECTOR</span> nval <span style="color: #990000">=</span> S3D<span style="color: #990000">::</span><span style="font-weight: bold"><span style="color: #000000">CalcTriNorm</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// Shape2</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// Note: we reuse the IFSG* wrappers to create and manipulate new</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// data structures.</span></span> + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + shape<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>tx1 <span style="color: #990000">);</span> + face<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// vertices</span></span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// indices</span></span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">0</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">1</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">2</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// normals</span></span> + nval <span style="color: #990000">=</span> S3D<span style="color: #990000">::</span><span style="font-weight: bold"><span style="color: #000000">CalcTriNorm</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + <span style="font-style: italic"><span style="color: #9A1900">// color (red)</span></span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.9</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetShininess</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.1</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// Shape3</span></span> + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + shape<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>tx1 <span style="color: #990000">);</span> + face<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// vertices</span></span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// indices</span></span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">0</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">1</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">2</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// normals</span></span> + nval <span style="color: #990000">=</span> S3D<span style="color: #990000">::</span><span style="font-weight: bold"><span style="color: #000000">CalcTriNorm</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// color (green)</span></span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.1</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.9</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetShininess</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.1</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// Shape4</span></span> + <span style="font-style: italic"><span style="color: #9A1900">//</span></span> + shape<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>tx1 <span style="color: #990000">);</span> + face<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>face <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// vertices</span></span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + cp<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// indices</span></span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">0</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">1</span> <span style="color: #990000">);</span> + coordIdx<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #993399">2</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// normals</span></span> + nval <span style="color: #990000">=</span> S3D<span style="color: #990000">::</span><span style="font-weight: bold"><span style="color: #000000">CalcTriNorm</span></span><span style="color: #990000">(</span> vert<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">],</span> vert<span style="color: #990000">[</span><span style="color: #993399">2</span><span style="color: #990000">]</span> <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + np<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> nval <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// color (blue)</span></span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>shape <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.1</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.0</span><span style="color: #990000">,</span> <span style="color: #993399">0.9</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span><span style="color: #990000">,</span> <span style="color: #993399">0.2</span> <span style="color: #990000">);</span> + material<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetShininess</span></span><span style="color: #990000">(</span> <span style="color: #993399">0.1</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// create a copy of the entire tetrahedron shifted Z+2 and rotated 2/3PI</span></span> + IFSG_TRANSFORM<span style="color: #990000">*</span> tx2 <span style="color: #990000">=</span> <span style="color: #008080">new</span> <span style="font-weight: bold"><span style="color: #000000">IFSG_TRANSFORM</span></span><span style="color: #990000">(</span> tx0<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">GetRawPtr</span></span><span style="color: #990000">()</span> <span style="color: #990000">);</span> + tx2<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">AddRefNode</span></span><span style="color: #990000">(</span> <span style="color: #990000">*</span>tx1 <span style="color: #990000">);</span> + tx2<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetTranslation</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">(</span> <span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="color: #993399">2</span> <span style="color: #990000">)</span> <span style="color: #990000">);</span> + tx2<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">SetRotation</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #000000">SGVECTOR</span></span><span style="color: #990000">(</span> <span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="color: #993399">1</span> <span style="color: #990000">),</span> M_PI<span style="color: #990000">*</span><span style="color: #993399">2.0</span><span style="color: #990000">/</span><span style="color: #993399">3.0</span> <span style="color: #990000">);</span> + + SGNODE<span style="color: #990000">*</span> data <span style="color: #990000">=</span> tx0<span style="color: #990000">-></span><span style="font-weight: bold"><span style="color: #000000">GetRawPtr</span></span><span style="color: #990000">();</span> + + <span style="font-style: italic"><span style="color: #9A1900">// delete the wrappers</span></span> + <span style="color: #008080">delete</span> shape<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> face<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> coordIdx<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> material<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> cp<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> np<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> tx0<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> tx1<span style="color: #990000">;</span> + <span style="color: #008080">delete</span> tx2<span style="color: #990000">;</span> + + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #990000">(</span>SCENEGRAPH<span style="color: #990000">*)</span>data<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span></tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_application_programming_interface_api">3. Application Programming Interface (API)</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Plugins are implemented via Application Programming Interface (API) +implementations. Each Plugin Class has its specific API and in the +3D Plugin tutorials we have seen examples of the implementation of +the 3D Plugin API as declared by the header 3d_plugin.h. Plugins +may also rely on other APIs defined within the KiCad source tree; +in the case of 3D plugins, all plugins which support visualization +of models must interact with the Scene Graph API as declared in +the header ifsg_all.h and its included headers.</p></div> +<div class="paragraph"><p>This section describes the details of available Plugin Class APIs +and other KiCad APIs which may be required for implementations of +plugin classes.</p></div> +<div class="sect2"> +<h3 id="_plugin_class_apis">3.1. Plugin Class APIs</h3> +<div class="paragraph"><p>There is currently only one plugin class declared for KiCad and +this is the 3D Plugin Class. All KiCad plugin classes must implement +a basic set of functions declared in the header file kicad_plugin.h; +these declarations shall be referred to as the Base Kicad Plugin Class. +No implementation of the Base Kicad Plugin Class exists; the header file +exists purely to ensure that plugin developers implement these +defined functions in each plugin implementation.</p></div> +<div class="paragraph"><p>Within KiCad, each instance of a Plugin Loader implements the API +presented by a plugin as though the Plugin Loader is a class providing +the plugin’s services. This is achieved by the Plugin Loader class +providing a public interface containing function names which are +similar to those implemented by the plugin; the argument lists may +vary to accommodate the need to inform the user of any problems which +may be encountered if, for example, no plugin is loaded. Internally +the Plugin Loader uses a stored pointer to each API function to +invoke each function on behalf of the user.</p></div> +<div class="sect3"> +<h4 id="_api_base_kicad_plugin_class">3.1.1. API: Base Kicad Plugin Class</h4> +<div class="paragraph"><p>The Base Kicad Plugin Class is defined by the header file kicad_plugin.h. +This header must be included in the declaration of all other plugin +classes; for example see the 3D Plugin Class declaration in the +header file 3d_plugin.h. The prototypes for these functions were briefly +described in <a href="#REF:PLUGIN_CLASSES">Plugin Classes</a>. The API is implemented +by the base plugin loader as defined in pluginldr.cpp.</p></div> +<div class="paragraph"><p>To help make sense of the functions required by the base kicad plugin header +we must look at what happens in the base Plugin Loader class. The Plugin +Loader class declares a virtual function <span class="monospaced">Open()</span> which takes the full +path to the plugin to be loaded. The implementation of the <span class="monospaced">Open()</span> function +within a specific plugin class loader will initially invoke the protected +<span class="monospaced">open()</span> function of the base plugin loader; this base <span class="monospaced">open()</span> function +attempts to find the address of each of the required basic plugin functions; +once the addresses of each function have been retrieved, a number of checks +are enforced:</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +Plugin <span class="monospaced">GetKicadPluginClass()</span> is invoked and the result is compared to +the Plugin Class string provided by the Plugin Loader implementation; if +these strings do not match then the opened plugin is not intended for the +Plugin Loader instance. +</p> +</li> +<li> +<p> +Plugin <span class="monospaced">GetClassVersion()</span> is invoked to retrieve the Plugin Class API Version +implemented by the plugin. +</p> +</li> +<li> +<p> +Plugin Loader virtual <span class="monospaced">GetLoaderVersion()</span> function is invoked to retrieve the +Plugin Class API Version implemented by the loader +</p> +</li> +<li> +<p> +The Plugin Class API Version reported by the plugin and the loader are +required to have the same Major Version number, otherwise they are +considered incompatible. This is the most basic version test and it is +enforced by the base plugin loader. +</p> +</li> +<li> +<p> +Plugin <span class="monospaced">CheckClassVersion()</span> is invoked with the Plugin Class API Version +information of the Plugin Loader; if the Plugin supports the given version +then it returns <span class="monospaced">true</span> to indicate success, in which case the loader creates +a PluginInfo string based on the results of <span class="monospaced">GetKicadPluginName()</span> and +<span class="monospaced">GetPluginVersion()</span>, and the plugin loading procedure +continues within the Plugin Loader’s <span class="monospaced">Open()</span> implementation. +</p> +</li> +</ol></div> +</div> +<div class="sect3"> +<h4 id="_api_3d_plugin_class">3.1.2. API: 3D Plugin Class</h4> +<div class="paragraph"><p>The 3D Plugin Class is declared by the header file 3d_plugin.h and it +extends the required plugin functions as described in +<a href="#REF:CLASS_PLUGIN_3D">Plugin Class: PLUGIN_3D</a>. The corresponding +Plugin Loader is defined in pluginldr3D.cpp and the loader implements +the following public functions in addition to the required API functions:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/* Open the plugin specified by the full path "aFullFileName" */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">Open</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> wxString<span style="color: #990000">&</span> aFullFileName <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Close the currently opened plugin */</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">Close</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* Retrieve the Plugin Class API Version implemented by this Plugin Loader */</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetLoaderVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p>The required 3D Plugin Class functions are exposed via the +following functions:</p></div> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/* returns the Plugin Class or NULL if no plugin loaded */</span></span> +<span style="color: #009900">char</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginClass</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* returns false if no plugin loaded */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">GetClassVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* returns false if the class version check fails or no plugin is loaded */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CheckClassVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span> Revision <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/* returns the Plugin Name or NULL if no plugin loaded */</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetKicadPluginName</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> returns false if no plugin is loaded, otherwise the arguments</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> contain the result of GetPluginVersion()</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">GetVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">);</span> + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> sets aPluginInfo to an empty string if no plugin is loaded,</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> otherwise aPluginInfo is set to a string of the form:</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> [NAME]:[MAJOR].[MINOR].[PATCH].[REVISION] where</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> NAME = name provided by GetKicadPluginClass()</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> MAJOR, MINOR, PATCH, REVISION = version information from</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> GetPluginVersion()</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPluginInfo</span></span><span style="color: #990000">(</span> std<span style="color: #990000">::</span>string<span style="color: #990000">&</span> aPluginInfo <span style="color: #990000">);</span></tt></pre></div></div> +<div class="paragraph"><p>In typical situations, the user would do the following:</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +Create an instance of <span class="monospaced">KICAD_PLUGIN_LDR_3D</span> +</p> +</li> +<li> +<p> +Invoke <span class="monospaced">Open( "/path/to/myplugin.so" )</span> to open a specific plugin; +the return value must be checked to ensure that the plugin loaded +as desired. +</p> +</li> +<li> +<p> +Invoke any of the 3D Plugin Class calls as exposed by <span class="monospaced">KICAD_PLUGIN_LDR_3D</span> +</p> +</li> +<li> +<p> +Invoke <span class="monospaced">Close()</span> to close (unlink) the plugin +</p> +</li> +<li> +<p> +Destroy the <span class="monospaced">KICAD_PLUGIN_LDR_3D</span> instance +</p> +</li> +</ol></div> +</div> +</div> +<div class="sect2"> +<h3 id="_scenegraph_class_apis">3.2. Scenegraph Class APIs</h3> +<div class="paragraph"><p>The Scenegraph Class API is defined by the header <span class="monospaced">ifsg_all.h</span> and its +included headers. The API consists of a number of helper routines with +the namespace <span class="monospaced">S3D</span> as defined in <span class="monospaced">ifsg_api.h</span> and wrapper classes defined +by the various <span class="monospaced">ifsg_*.h</span> headers; the wrappers support the underlying +scene graph classes which, taken together, form a scene graph structure +which is compatible with VRML2.0 static scene graphs. The headers, +structures, classes and their public functions are as follows:</p></div> +<div class="listingblock"> +<div class="title">sg_version.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Defines version information of the SceneGraph Classes.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> All plugins which use the scenegraph class should include this header</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> and check the version information against the version reported by</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> S3D::GetLibVersion() to ensure compatibility</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> KICADSG_VERSION_MAJOR <span style="color: #993399">2</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> KICADSG_VERSION_MINOR <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> KICADSG_VERSION_PATCH <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> KICADSG_VERSION_REVISION <span style="color: #993399">0</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">sg_types.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> Defines the SceneGraph Class Types; these types</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> are closely related to VRML2.0 node types.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +namespace S3D +<span style="color: #FF0000">{</span> + <span style="font-weight: bold"><span style="color: #0000FF">enum</span></span> SGTYPES + <span style="color: #FF0000">{</span> + SGTYPE_TRANSFORM <span style="color: #990000">=</span> <span style="color: #993399">0</span><span style="color: #990000">,</span> + SGTYPE_APPEARANCE<span style="color: #990000">,</span> + SGTYPE_COLORS<span style="color: #990000">,</span> + SGTYPE_COLORINDEX<span style="color: #990000">,</span> + SGTYPE_FACESET<span style="color: #990000">,</span> + SGTYPE_COORDS<span style="color: #990000">,</span> + SGTYPE_COORDINDEX<span style="color: #990000">,</span> + SGTYPE_NORMALS<span style="color: #990000">,</span> + SGTYPE_SHAPE<span style="color: #990000">,</span> + SGTYPE_END + <span style="color: #FF0000">}</span><span style="color: #990000">;</span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p>The <span class="monospaced">sg_base.h</span> header contains declarations of basic data types used +by the scenegraph classes.</p></div> +<div class="listingblock"> +<div class="title">sg_base.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> This is an RGB color model equivalent to the VRML2.0</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> RGB model where each color may have a value within the</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> range [0..1].</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +class SGCOLOR +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">SGCOLOR</span></span><span style="color: #990000">();</span> + <span style="font-weight: bold"><span style="color: #000000">SGCOLOR</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aRVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aGVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aBVal <span style="color: #990000">);</span> + + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetColor</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span><span style="color: #990000">&</span> aRedVal<span style="color: #990000">,</span> <span style="color: #009900">float</span><span style="color: #990000">&</span> aGreenVal<span style="color: #990000">,</span> <span style="color: #009900">float</span><span style="color: #990000">&</span> aBlueVal <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetColor</span></span><span style="color: #990000">(</span> SGCOLOR<span style="color: #990000">&</span> aColor <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetColor</span></span><span style="color: #990000">(</span> SGCOLOR<span style="color: #990000">*</span> aColor <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetColor</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aRedVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aGreenVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aBlueVal <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetColor</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">&</span> aColor <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetColor</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">*</span> aColor <span style="color: #990000">);</span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span> + + +class SGPOINT +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="color: #009900">double</span> x<span style="color: #990000">;</span> + <span style="color: #009900">double</span> y<span style="color: #990000">;</span> + <span style="color: #009900">double</span> z<span style="color: #990000">;</span> + +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">();</span> + <span style="font-weight: bold"><span style="color: #000000">SGPOINT</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aXVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aYVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aZVal <span style="color: #990000">);</span> + + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPoint</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span><span style="color: #990000">&</span> aXVal<span style="color: #990000">,</span> <span style="color: #009900">double</span><span style="color: #990000">&</span> aYVal<span style="color: #990000">,</span> <span style="color: #009900">double</span><span style="color: #990000">&</span> aZVal <span style="color: #990000">);</span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPoint</span></span><span style="color: #990000">(</span> SGPOINT<span style="color: #990000">&</span> aPoint <span style="color: #990000">);</span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetPoint</span></span><span style="color: #990000">(</span> SGPOINT<span style="color: #990000">*</span> aPoint <span style="color: #990000">);</span> + + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">SetPoint</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aXVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aYVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aZVal <span style="color: #990000">);</span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">SetPoint</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> aPoint <span style="color: #990000">);</span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span> + + +<span style="font-style: italic"><span style="color: #9A1900">/*</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> A SGVECTOR has 3 components (x,y,z) similar to a point; however</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> a vector ensures that the stored values are normalized and</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> prevents direct manipulation of the component variables.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +class SGVECTOR +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">SGVECTOR</span></span><span style="color: #990000">();</span> + <span style="font-weight: bold"><span style="color: #000000">SGVECTOR</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aXVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aYVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aZVal <span style="color: #990000">);</span> + + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">GetVector</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span><span style="color: #990000">&</span> aXVal<span style="color: #990000">,</span> <span style="color: #009900">double</span><span style="color: #990000">&</span> aYVal<span style="color: #990000">,</span> <span style="color: #009900">double</span><span style="color: #990000">&</span> aZVal <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">SetVector</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aXVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aYVal<span style="color: #990000">,</span> <span style="color: #009900">double</span> aZVal <span style="color: #990000">);</span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">SetVector</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGVECTOR<span style="color: #990000">&</span> aVector <span style="color: #990000">);</span> + + SGVECTOR<span style="color: #990000">&</span> operator<span style="color: #990000">=(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGVECTOR<span style="color: #990000">&</span> source <span style="color: #990000">);</span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p>The <span class="monospaced">IFSG_NODE</span> class is the base class for all scenegraph nodes. All +scenegraph objects implement the public functions of this class but in +some cases a particular function may have no meaning for a specific +class.</p></div> +<div class="listingblock"> +<div class="title">ifsg_node.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #008080">class</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_NODE</span></span><span style="color: #990000">();</span> + virtual <span style="color: #990000">~</span><span style="font-weight: bold"><span style="color: #000000">IFSG_NODE</span></span><span style="color: #990000">();</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Destroy</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * deletes the scenegraph object held by this wrapper</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #009900">void</span> <span style="font-weight: bold"><span style="color: #000000">Destroy</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Attach</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * associates a given SGNODE* with this wrapper</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + virtual <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">Attach</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">)</span> <span style="color: #990000">=</span> <span style="color: #993399">0</span><span style="color: #990000">;</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function NewNode</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * creates a new node to associate with this wrapper</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + virtual <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">)</span> <span style="color: #990000">=</span> <span style="color: #993399">0</span><span style="color: #990000">;</span> + virtual <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">NewNode</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">)</span> <span style="color: #990000">=</span> <span style="color: #993399">0</span><span style="color: #990000">;</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function GetRawPtr()</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * returns the raw internal SGNODE pointer</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGNODE<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetRawPtr</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function GetNodeType</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * returns the type of this node instance</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + S3D<span style="color: #990000">::</span><span style="color: #008080">SGTYPES</span> <span style="font-weight: bold"><span style="color: #000000">GetNodeType</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function GetParent</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * returns a pointer to the parent SGNODE of this object</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * or NULL if the object has no parent (ie. top level transform)</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * or if the wrapper is not currently associated with an SGNODE.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGNODE<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetParent</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function SetParent</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * sets the parent SGNODE of this object.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aParent [in] is the desired parent node</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> true if the operation succeeds; false if</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * the given node is not allowed to be a parent to</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * the derived object.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetParent</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function GetNodeTypeName</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * returns the text representation of the node type</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * or NULL if the node somehow has an invalid type</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetNodeTypeName</span></span><span style="color: #990000">(</span> S3D<span style="color: #990000">::</span><span style="color: #008080">SGTYPES</span> aNodeType <span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span><span style="color: #990000">;</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function AddRefNode</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * adds a reference to an existing node which is not owned by</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * (not a child of) this node.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> true on success</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddRefNode</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddRefNode</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aNode <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function AddChildNode</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * adds a node as a child owned by this node.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> true on success</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddChildNode</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddChildNode</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aNode <span style="color: #990000">);</span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_TRANSFORM</span> is similar to a VRML2.0 Transform node; it may +contain any number of child IFSG_SHAPE and IFSG_TRANSFORM nodes +and any number of referenced IFSG_SHAPE and IFSG_TRANSFORM nodes. +A valid scenegraph must have a single <span class="monospaced">IFSG_TRANSFORM</span> object +as a root.</p></div> +<div class="listingblock"> +<div class="title">ifsg_transform.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_TRANSFORM</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for the VRML compatible TRANSFORM block class SCENEGRAPH</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_TRANSFORM <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_TRANSFORM</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_TRANSFORM</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetScaleOrientation</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGVECTOR<span style="color: #990000">&</span> aScaleAxis<span style="color: #990000">,</span> <span style="color: #009900">double</span> aAngle <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetRotation</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGVECTOR<span style="color: #990000">&</span> aRotationAxis<span style="color: #990000">,</span> <span style="color: #009900">double</span> aAngle <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetScale</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> aScale <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetScale</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aScale <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetCenter</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> aCenter <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetTranslation</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> aTranslation <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_SHAPE</span> is similar to a VRML2.0 Shape node; it must contain +a single child or reference FACESET node and may contain a +single child or reference APPEARANCE node.</p></div> +<div class="listingblock"> +<div class="title">ifsg_shape.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_SHAPE</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for the SGSHAPE class</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_SHAPE <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_SHAPE</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_SHAPE</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_SHAPE</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_APPEARANCE</span> is similar to a VRML2.0 Appearance node, however +at the moment it only represents the equivalent of an Appearance +node containing a Material node.</p></div> +<div class="listingblock"> +<div class="title">ifsg_appearance.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #008080">class</span> IFSG_APPEARANCE <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_APPEARANCE</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_APPEARANCE</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_APPEARANCE</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetEmissive</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aRVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aGVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aBVal <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetEmissive</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">*</span> aRGBColor <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetEmissive</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">&</span> aRGBColor <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aRVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aGVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aBVal <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">*</span> aRGBColor <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetDiffuse</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">&</span> aRGBColor <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aRVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aGVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aBVal <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">*</span> aRGBColor <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetSpecular</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">&</span> aRGBColor <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aRVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aGVal<span style="color: #990000">,</span> <span style="color: #009900">float</span> aBVal <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">*</span> aRGBColor <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetAmbient</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">&</span> aRGBColor <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetShininess</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aShininess <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetTransparency</span></span><span style="color: #990000">(</span> <span style="color: #009900">float</span> aTransparency <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/* the following functions make no sense within an</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> appearance node and always return a failure code</span></span> + +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_FACESET</span> is similar to a VRML2.0 Geometry node which +contains an IndexedFaceSet node. It must contain a single +child or reference COORDS node, a single child COORDINDEX +node, and a single child or reference NORMALS node; in +addition there may be a single child or reference COLORS node. +A simplistic normals calculation function is provided to aid +the user in assigning normal values to surfaces. The deviations +from the VRML2.0 analogue are as follows:</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +normals are always per-vertex +</p> +</li> +<li> +<p> +colors are always per vertex +</p> +</li> +<li> +<p> +the coordinate index set must describe triangular faces only +</p> +</li> +</ol></div> +<div class="listingblock"> +<div class="title">ifsg_faceset.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_FACESET</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for the SGFACESET class</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_FACESET <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_FACESET</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_FACESET</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_FACESET</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">CalcNormals</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">**</span> aPtr <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">ifsg_coords.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_COORDS</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for SGCOORDS</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_COORDS <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDS</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDS</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDS</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">GetCoordsList</span></span><span style="color: #990000">(</span> size_t<span style="color: #990000">&</span> aListSize<span style="color: #990000">,</span> SGPOINT<span style="color: #990000">*&</span> aCoordsList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetCoordsList</span></span><span style="color: #990000">(</span> <span style="color: #008080">size_t</span> aListSize<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">*</span> aCoordsList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aXValue<span style="color: #990000">,</span> <span style="color: #009900">double</span> aYValue<span style="color: #990000">,</span> <span style="color: #009900">double</span> aZValue <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddCoord</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> aPoint <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/* the following functions make no sense within a</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> coords node and always return a failure code</span></span> + +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_COORDINDEX</span> is similar to a VRML2.0 coordIdx[] +set; however it must exclusively describe triangular +faces, which implies that the total number of indices +is divisible by 3.</p></div> +<div class="listingblock"> +<div class="title">ifsg_coordindex.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_COORDINDEX</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for SGCOORDINDEX</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_COORDINDEX <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_INDEX +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDINDEX</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDINDEX</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COORDINDEX</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">GetIndices</span></span><span style="color: #990000">(</span> size_t<span style="color: #990000">&</span> nIndices<span style="color: #990000">,</span> <span style="color: #009900">int</span><span style="color: #990000">*&</span> aIndexList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetIndices</span></span><span style="color: #990000">(</span> <span style="color: #008080">size_t</span> nIndices<span style="color: #990000">,</span> <span style="color: #009900">int</span><span style="color: #990000">*</span> aIndexList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddIndex</span></span><span style="color: #990000">(</span> <span style="color: #009900">int</span> aIndex <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/* the following functions make no sense within a</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> coordindex node and always return a failure code</span></span> + +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_NORMALS</span> is equivalent to a VRML2.0 Normals node.</p></div> +<div class="listingblock"> +<div class="title">ifsg_normals.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_NORMALS</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for the SGNORMALS class</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_NORMALS <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_NORMALS</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_NORMALS</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_NORMALS</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">GetNormalList</span></span><span style="color: #990000">(</span> size_t<span style="color: #990000">&</span> aListSize<span style="color: #990000">,</span> SGVECTOR<span style="color: #990000">*&</span> aNormalList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetNormalList</span></span><span style="color: #990000">(</span> <span style="color: #008080">size_t</span> aListSize<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGVECTOR<span style="color: #990000">*</span> aNormalList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aXValue<span style="color: #990000">,</span> <span style="color: #009900">double</span> aYValue<span style="color: #990000">,</span> <span style="color: #009900">double</span> aZValue <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddNormal</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGVECTOR<span style="color: #990000">&</span> aNormal <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/* the following functions make no sense within a</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> normals node and always return a failure code</span></span> + +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p><span class="monospaced">IFSG_COLORS</span> is similar to a VRML2.0 colors[] set.</p></div> +<div class="listingblock"> +<div class="title">ifsg_colors.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Class IFSG_COLORS</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * is the wrapper for SGCOLORS</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + +<span style="color: #008080">class</span> IFSG_COLORS <span style="color: #990000">:</span> <span style="color: #008080">public</span> IFSG_NODE +<span style="color: #FF0000">{</span> +<span style="font-weight: bold"><span style="color: #008080">public:</span></span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COLORS</span></span><span style="color: #990000">(</span> <span style="color: #009900">bool</span> create <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COLORS</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent <span style="color: #990000">);</span> + <span style="font-weight: bold"><span style="color: #000000">IFSG_COLORS</span></span><span style="color: #990000">(</span> IFSG_NODE<span style="color: #990000">&</span> aParent <span style="color: #990000">);</span> + + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">GetColorList</span></span><span style="color: #990000">(</span> size_t<span style="color: #990000">&</span> aListSize<span style="color: #990000">,</span> SGCOLOR<span style="color: #990000">*&</span> aColorList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">SetColorList</span></span><span style="color: #990000">(</span> <span style="color: #008080">size_t</span> aListSize<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">*</span> aColorList <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddColor</span></span><span style="color: #990000">(</span> <span style="color: #009900">double</span> aRedValue<span style="color: #990000">,</span> <span style="color: #009900">double</span> aGreenValue<span style="color: #990000">,</span> <span style="color: #009900">double</span> aBlueValue <span style="color: #990000">);</span> + <span style="color: #009900">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddColor</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGCOLOR<span style="color: #990000">&</span> aColor <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/* various base class functions not shown here */</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/* the following functions make no sense within a</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> normals node and always return a failure code</span></span> + +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddRefNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( SGNODE* aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> bool AddChildNode( IFSG_NODE& aNode );</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p>The remaining API functions are defined in <span class="monospaced">ifsg_api.h</span> as follows:</p></div> +<div class="listingblock"> +<div class="title">ifsg_api.h</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.7 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>namespace S3D +<span style="color: #FF0000">{</span> + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function GetLibVersion retrieves version information of the</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * kicad_3dsg library</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">GetLibVersion</span></span><span style="color: #990000">(</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Major<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Minor<span style="color: #990000">,</span> + <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Patch<span style="color: #990000">,</span> <span style="color: #009900">unsigned</span> <span style="color: #009900">char</span><span style="color: #990000">*</span> Revision <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// functions to extract information from SGNODE pointers</span></span> + <span style="color: #008080">SGLIB_API</span> S3D<span style="color: #990000">::</span><span style="color: #008080">SGTYPES</span> <span style="font-weight: bold"><span style="color: #000000">GetSGNodeType</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + <span style="color: #008080">SGLIB_API</span> SGNODE<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetSGNodeParent</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + SGLIB_API <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddSGNodeRef</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent<span style="color: #990000">,</span> SGNODE<span style="color: #990000">*</span> aChild <span style="color: #990000">);</span> + SGLIB_API <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">AddSGNodeChild</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aParent<span style="color: #990000">,</span> SGNODE<span style="color: #990000">*</span> aChild <span style="color: #990000">);</span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">AssociateSGNodeWrapper</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aObject<span style="color: #990000">,</span> SGNODE<span style="color: #990000">**</span> aRefPtr <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function CalcTriNorm</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * returns the normal vector of a triangle described by vertices p1, p2, p3</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">SGVECTOR</span> <span style="font-weight: bold"><span style="color: #000000">CalcTriNorm</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> p1<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> p2<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> SGPOINT<span style="color: #990000">&</span> p3 <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function WriteCache</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * writes the SGNODE tree to a binary cache file</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aFileName is the name of the file to write</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> overwrite must be set to true to overwrite an existing file</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aNode is any node within the node tree which is to be written</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> true on success</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">WriteCache</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> aFileName<span style="color: #990000">,</span> <span style="color: #009900">bool</span> overwrite<span style="color: #990000">,</span> SGNODE<span style="color: #990000">*</span> aNode<span style="color: #990000">,</span> + <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> aPluginInfo <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function ReadCache</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * reads a binary cache file and creates an SGNODE tree</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aFileName is the name of the binary cache file to be read</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> NULL on failure, on success a pointer to the top level SCENEGRAPH node;</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * if desired this node can be associated with an IFSG_TRANSFORM wrapper via</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * the IFSG_TRANSFORM::Attach() function.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #008080">SGLIB_API</span> SGNODE<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">ReadCache</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> aFileName<span style="color: #990000">,</span> <span style="color: #009900">void</span><span style="color: #990000">*</span> aPluginMgr<span style="color: #990000">,</span> + <span style="color: #009900">bool</span> <span style="color: #990000">(*</span>aTagCheck<span style="color: #990000">)(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*,</span> <span style="color: #009900">void</span><span style="color: #990000">*</span> <span style="color: #990000">)</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function WriteVRML</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * writes out the given node and its subnodes to a VRML2 file</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> filename is the name of the output file</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> overwrite should be set to true to overwrite an existing VRML file</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aTopNode is a pointer to a SCENEGRAPH object representing the VRML scene</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> reuse should be set to true to make use of VRML DEF/USE features</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> true on success</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">bool</span> <span style="font-weight: bold"><span style="color: #000000">WriteVRML</span></span><span style="color: #990000">(</span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #009900">char</span><span style="color: #990000">*</span> filename<span style="color: #990000">,</span> <span style="color: #009900">bool</span> overwrite<span style="color: #990000">,</span> SGNODE<span style="color: #990000">*</span> aTopNode<span style="color: #990000">,</span> + <span style="color: #009900">bool</span> reuse<span style="color: #990000">,</span> <span style="color: #009900">bool</span> renameNodes <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// NOTE: The following functions are used in combination to create a VRML</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// assembly which may use various instances of each SG* representation of a module.</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// A typical use case would be:</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 1. invoke 'ResetNodeIndex()' to reset the global node name indices</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 2. for each model pointer provided by 'S3DCACHE->Load()', invoke 'RenameNodes()' once;</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// this ensures that all nodes have a unique name to present to the final output file.</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// Internally, RenameNodes() will only rename the given node and all Child subnodes;</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// nodes which are only referenced will not be renamed. Using the pointer supplied</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// by 'S3DCACHE->Load()' ensures that all nodes but the returned node (top node) are</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// children of at least one node, so all nodes are given unique names.</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 3. if SG* trees are created independently of S3DCACHE->Load() the user must invoke</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// RenameNodes() as appropriate to ensure that all nodes have a unique name</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 4. create an assembly structure by creating new IFSG_TRANSFORM nodes as appropriate</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// for each instance of a component; the component base model as returned by</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// S3DCACHE->Load() may be added to these IFSG_TRANSFORM nodes via 'AddRefNode()';</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// set the offset, rotation, etc of the IFSG_TRANSFORM node to ensure correct</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 5. Ensure that all new IFSG_TRANSFORM nodes are placed as child nodes within a</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// top level IFSG_TRANSFORM node in preparation for final node naming and output</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 6. Invoke RenameNodes() on the top level assembly node</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 7. Invoke WriteVRML() as normal, with renameNodes = false, to write the entire assembly</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// structure to a single VRML file</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// 8. Clean up by deleting any extra IFSG_TRANSFORM wrappers and their underlying SG*</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// classes which have been created solely for the assembly output</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function ResetNodeIndex</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * resets the global SG* class indices</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aNode may be any valid SGNODE</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">ResetNodeIndex</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function RenameNodes</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * renames a node and all children nodes based on the current</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * values of the global SG* class indices</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aNode is a top level node</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">RenameNodes</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function DestroyNode</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * deletes the given SG* class node. This function makes it possible</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * to safely delete an SG* node without associating the node with</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * its corresponding IFSG* wrapper.</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">DestroyNode</span></span><span style="color: #990000">(</span> SGNODE<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">// NOTE: The following functions facilitate the creation and destruction</span></span> + <span style="font-style: italic"><span style="color: #9A1900">// of data structures for rendering</span></span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function GetModel</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * creates an S3DMODEL representation of aNode (raw data, no transforms)</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> *</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@param</span><span style="font-style: italic"><span style="color: #9A1900"> aNode is the node to be transcribed into an S3DMODEL representation</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * </span></span><span style="color: #009900">@return</span><span style="font-style: italic"><span style="color: #9A1900"> an S3DMODEL representation of aNode on success, otherwise NULL</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #008080">SGLIB_API</span> S3DMODEL<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">GetModel</span></span><span style="color: #990000">(</span> SCENEGRAPH<span style="color: #990000">*</span> aNode <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Destroy3DModel</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * frees memory used by an S3DMODEL structure and sets the pointer to</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * the structure to NULL</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">Destroy3DModel</span></span><span style="color: #990000">(</span> S3DMODEL<span style="color: #990000">**</span> aModel <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Free3DModel</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * frees memory used internally by an S3DMODEL structure</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">Free3DModel</span></span><span style="color: #990000">(</span> S3DMODEL<span style="color: #990000">&</span> aModel <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Free3DMesh</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * frees memory used internally by an SMESH structure</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">Free3DMesh</span></span><span style="color: #990000">(</span> SMESH<span style="color: #990000">&</span> aMesh <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function New3DModel</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * creates and initializes an S3DMODEL struct</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + <span style="color: #008080">SGLIB_API</span> S3DMODEL<span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #000000">New3DModel</span></span><span style="color: #990000">(</span> <span style="color: #009900">void</span> <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Init3DMaterial</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * initializes an SMATERIAL struct</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">Init3DMaterial</span></span><span style="color: #990000">(</span> SMATERIAL<span style="color: #990000">&</span> aMat <span style="color: #990000">);</span> + + <span style="font-style: italic"><span style="color: #9A1900">/**</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * Function Init3DMesh</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> * creates and initializes an SMESH struct</span></span> +<span style="font-style: italic"><span style="color: #9A1900"> */</span></span> + SGLIB_API <span style="color: #008080">void</span> <span style="font-weight: bold"><span style="color: #000000">Init3DMesh</span></span><span style="color: #990000">(</span> SMESH<span style="color: #990000">&</span> aMesh <span style="color: #990000">);</span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span></tt></pre></div></div> +<div class="paragraph"><p>For examples of actual usage of the Scenegraph API see the +3D Plugin DEMO2 tutorial and the kicad VRML1, VRML2, and X3D +parsers.</p></div> +</div> +</div> +</div> +</div> +<div id="footnotes"><hr></div> +<div id="footer"> +<div id="footer-text"> +Last updated 2017-08-24 22:21:56 BST +</div> +</div> +</body> +</html> |