1 /*
2  * This program source code file is part of KiCad, a free EDA CAD application.
3  *
4  * Copyright (C) 2015 Cirilo Bernardo <cirilo.bernardo@gmail.com>
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, you may find one here:
18  * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
19  * or you may search the http://www.gnu.org website for the version 2 license,
20  * or you may write to the Free Software Foundation, Inc.,
21  * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
22  */
23 
24 /**
25  * @file ifsg_node.h
26  * defines the wrapper of the base class SG_NODE
27  */
28 
29 /*
30  * NOTES:
31  * 1. The IFSG wrapper classes shall be aimed at creating a VRML-like
32  *    intermediate scenegraph representation. Although objects are
33  *    readily created and added to the structure, no provision shall
34  *    be made to inspect the structures in detail. For example the
35  *    SCENEGRAPH class may contain various SGSHAPE and SCENEGRAPH
36  *    nodes but there shall be no provision to extract those nodes.
37  *    This was done because in principle all the detailed data shall
38  *    only be handled within the SG* classes and only data processed
39  *    via GetRenderData() shall be available via the wrappers.
40  */
41 
42 #ifndef IFSG_NODE_H
43 #define IFSG_NODE_H
44 
45 #include "plugins/3dapi/sg_base.h"
46 #include "plugins/3dapi/sg_types.h"
47 
48 class SGNODE;
49 
50 /**
51  * IFSG_NODE
52  * represents the base class of all DLL-safe Scene Graph nodes
53  */
54 class SGLIB_API IFSG_NODE
55 {
56 protected:
57     SGNODE* m_node;
58 
59 public:
60     IFSG_NODE();
61     virtual ~IFSG_NODE();
62 
63     // deleted operators
64     IFSG_NODE( const IFSG_NODE& aParent ) = delete;
65     IFSG_NODE& operator= ( const IFSG_NODE& ) = delete;
66 
67     /**
68      * Function Destroy
69      * deletes the object held by this wrapper
70      */
71     void Destroy( void );
72 
73     /**
74      * Function Attach
75      * associates a given SGNODE* with this wrapper
76      */
77     virtual bool Attach( SGNODE* aNode ) = 0;
78 
79     /**
80      * Function NewNode
81      * creates a new node to associate with this wrapper
82      */
83     virtual bool NewNode( SGNODE* aParent ) = 0;
84     virtual bool NewNode( IFSG_NODE& aParent ) = 0;
85 
86     /**
87      * Function GetRawPtr()
88      * returns the raw internal SGNODE pointer
89      */
90     SGNODE* GetRawPtr( void ) noexcept;
91 
92     /**
93      * Function GetNodeType
94      * returns the type of this node instance
95      */
96     S3D::SGTYPES GetNodeType( void ) const;
97 
98     /**
99      * Function GetParent
100      * returns a pointer to the parent SGNODE of this object
101      * or NULL if the object has no parent (ie. top level transform).
102      */
103     SGNODE* GetParent( void ) const;
104 
105     /**
106      * Function SetParent
107      * sets the parent SGNODE of this object.
108      *
109      * @param aParent [in] is the desired parent node
110      * @return true if the operation succeeds; false if
111      * the given node is not allowed to be a parent to
112      * the derived object
113      */
114     bool SetParent( SGNODE* aParent );
115 
116     /**
117      * Function GetName
118      * returns a pointer to the node name (NULL if no name assigned)
119      */
120     const char* GetName( void );
121 
122     /**
123      * Function SetName
124      * sets the node's name; if the pointer passed is NULL
125      * then the node's name is erased
126      *
127      * @return true on success
128      */
129     bool SetName( const char *aName );
130 
131     /**
132      * Function GetNodeTypeName
133      * returns the text representation of the node type
134      * or NULL if the node somehow has an invalid type
135      */
136     const char * GetNodeTypeName( S3D::SGTYPES aNodeType ) const;
137 
138     /**
139      * Function FindNode searches the tree of linked nodes and returns a
140      * reference to the first node found with the given name. The reference
141      * is then typically added to another node via AddRefNode().
142      *
143      * @param aNodeName is the name of the node to search for
144      * @return is a valid node pointer on success, otherwise NULL
145      */
146     SGNODE* FindNode( const char *aNodeName );
147 
148     /**
149      * Function AddRefNode
150      * adds a reference to an existing node which is not owned by
151      * (not a child of) this node.
152      *
153      * @return true on success
154      */
155     bool AddRefNode( SGNODE* aNode );
156     bool AddRefNode( IFSG_NODE& aNode );
157 
158     /**
159      * Function AddChildNode
160      * adds a node as a child owned by this node.
161      *
162      * @return true on success
163      */
164     bool AddChildNode( SGNODE* aNode );
165     bool AddChildNode( IFSG_NODE& aNode );
166 };
167 
168 #endif  // IFSG_NODE_H
169