delta3d - Recent changes [en]

Road Map

2010-01-07T21:41:26Z

Extract "Group" Node Functionality, DeltaDrawable, Scene, and Environment:

← Older revision		Revision as of 21:41, 7 January 2010
(4 intermediate revisions not shown)
Line 1:		Line 1:
	= Road Map =		= Road Map =
-	''High-level items the Delta3D Development Team would like to see implemented''	+	''High-level items the Delta3D Development Team would like to see implemented, but not necessarily things the Team has funding for''
		+
		+	== Extract "Group" Node Functionality, DeltaDrawable, Scene, and Environment ==
		+	Come up with a better design to allow for parenting of DeltaDrawable. DeltaDrawable has the ability to have children, which Environment inherits. Perhaps Scene should also be a DeltaDrawable.
		+
		+	The GameManager needs to be reworked to allow for the parenting of DeltaDrawables (actors) as well, and remove the internal reference to Environment. The GameManager should only need to know about the "root" DeltaDrawable (typically a Scene).
		+
		+	Related cases:
		+
		+	[http://sourceforge.net/apps/mantisbt/delta3d/view.php?id=112 #112]
		+
		+	== Unify the Messaging System ==
		+	Combine the dtCore::Base and the GameManager messaging system into one. Everything should have the potential of sending and receiving messages.
		+
		+	== Extract the Actor Management from GameManager ==
		+	To make a reusable system which can be used other places (like STAGE), without incurring the dependency on GameManager.
		+
		+	== Isolate Dependency on Xerces XML ==
		+	There are many places in Delta3D where xml files are parsed and written, typically using Xerces API directly. Isolate the direct usage of Xerces by many files by creating a wrapper/interface to the xml parsing. This will make it easier for future XML parsing changes.

StyleGuide

2010-01-05T19:47:12Z

protected "[[StyleGuide]]" [edit=sysop] (indefinite) [move=sysop] (indefinite)

New page

CodingPractices

2010-01-05T19:30:14Z

added section on virtual methods

New page

== Delta3D Coding Practices ==

* Force the compiler to check for redundant includes with <tt>#ifndef</tt>, <tt>#define</tt>, <tt>#endif</tt>
* Use "Set" and "Get" for class members (e.g. <tt>SetName()</tt>, <tt>GetName(</tt>))
* No C-style casts. Use <tt>dynamic_cast</tt>, <tt>static_cast</tt>, or <tt>reinterpret_cast</tt>. If you are casting a primitive, try to use a C++ style cast like <tt>float(x)</tt> rather than <tt>(float)x</tt>. The exception to this is that g++ has a bug with two named types, so you have to do <tt>(unsigned long)(x)</tt>.
* No <tt>#pragma</tt> directives (they are compiler dependant).
* Singleton classes use <tt>GetInstance()</tt> which return by reference.
* Reference-counted classes (i.e. those that have <tt>osg::Referenced</tt> as a base) must have protected destructors. Store instances of Delta3D reference-counted classes in <tt>dtCore::RefPtr</tt>, but be careful to avoid circular references. Use an <tt>dtCore::ObserverPtr</tt> in circular reference cases.
* Don't use a <tt>char*</tt> for a string, instead use a <tt>std::string</tt>. When passing <tt>std::string</tt> to a function, use <tt>const str::string&</tt> unless you plan to change the string. When returning a string that is a member of a class, use <tt>const std::string&</tt> whenever possible. If you are returning a temporary, return const <tt>std::string</tt>.
* For <tt>std::string</tt> that are static for their lifetime, consider using the <tt>RefString</tt> instead.
* Prefer using references instead of pointers. If <tt>NULL</tt> is in the valid domain for your parameter or return value, the pointers are fine.
* Prefer using STL containers and algoritms over custom solutions.
* Don’t make methods that take RefPtrs as arguments or return them. The exception to this is when a method is creating something for you and returning it. In that case, returning the RefPtr tells the caller that they have the only handle to the object.
* Don’t use <tt>throw</tt> clauses on function declarations.
* Use Forward Declarations when possible. Do not use a Forward Declaration for variables contained in a <tt>RefPtr</tt>; <tt>#include</tt> the header file instead.
* Use the <tt>const</tt> keyword whenever possible: const methods, const parameters, const return values.
* Avoid long methods: Methods should be short and perform one function. If a long method is performing multiple functions in sequence (typically separated by comments), consider extracting the functionality into a separate method.
* Avoid long message chains: If a class asks one object for another object, which then asks for another object, consider an alternative solution to break the dependency list. See how the final object is used. Perhaps it can be supplied to the class directly, or obtained a different way.

== How to Deprecate Functionality ==
The purpose of deprecating is to allow the phasing out of older functionality, for new functionality, without causing compile or runtime errors with an existing code base.

=== The Laws of Deprecation: ===
# Existing code should continue to work using the old functionality, at least as well as it did before the deprecation.
# Developers should be notified when deprecated functionality is being used (compile warnings, runtime warnings, or both).
# Deprecated functionality should be documented when it was deprecated. Adding the date of deprecation in the source code comments is preferred. This allows the functionality to be removed later at an acceptable time frame.

=== Deprecating a Class Method ===
Here we are deprecating <tt>OldMethod(int)</tt> for <tt>NewMethod(float)</tt>. Note that we have:
# Dated the deprecation
# Ensured that OldMethod() will still work if called
# A compiler warning will be generated if OldMethod() is called (via <tt>DEPRECATE_FUNC</tt>)
# A deprecated log summary will be generated if OldMethod() is called, when run in debug mode (via <tt>DEPRECATE</tt>)

<pre>
#include <dtUtil/deprecationmgr.h>

class MyClass
{
...
bool NewMethod(float);

///deprecated 12/21/12
DEPRECATE_FUNC void OldMethod(int)
{
DEPRECATE("void MyClass::OldMethod(int)"
"bool MyClass::NewMethod(float)");

NewMethod(float(int)));
}
};
</pre>

=== Deprecating or Removing a Virtual Method ===
Deprecating virtual methods require some additional attention, since the user's derived instance will continue to compile without notice of deprecation. Using the <tt>BREAK_OVERRIDE</tt> macro will generate a compile error should the user try to overwrite a deprecated virtual method.

For example:
<pre>
...
virtual void GetTransform(Transform& xform, CoordSysEnum cs = ABS_CS) const; //new method
//virtual void GetTransform(Transform* xform, CoordSysEnum cs = ABS_CS) const; //old method
private:
//will cause compile error if user tries to overwrite this method
BREAK_OVERRIDE(GetTransform(const Transform*, CoordSysEnum)) ///deprecated 12/21/12
</pre>

Best Practices

2010-01-05T18:36:53Z

added links to the style guide and coding practices

← Older revision		Revision as of 18:36, 5 January 2010
Line 6:		Line 6:
	* [[Delta3DFileTypes\|Delta3D File Types]]		* [[Delta3DFileTypes\|Delta3D File Types]]
	* [[dtAnimBestPractices\|dtAnim]]		* [[dtAnimBestPractices\|dtAnim]]
		+	* [[StyleGuide\|Coding Style Guide]]
		+	* [[CodingPractices\|Coding Practices]]

TutorialHelloWorld

2010-01-05T17:14:58Z

added note about CMake versions

← Older revision		Revision as of 17:14, 5 January 2010
Line 209:		Line 209:

	==Project Files==		==Project Files==
-	We'll need to create a CMake script file so CMake knows about our project. Here's a simple <tt>CMakeLists.txt</tt> we can use that references our 3 files and creates an executable:	+	We'll need to create a CMake script file so CMake knows about our project. '''Note, we're using CMake 2.6 and later here.''' Here's a simple <tt>CMakeLists.txt</tt> we can use that references our 3 files and creates an executable:

	<pre>		<pre>

← Older revision		Revision as of 18:36, 5 January 2010
Line 6:		Line 6:
	* [[Delta3DFileTypes\|Delta3D File Types]]		* [[Delta3DFileTypes\|Delta3D File Types]]
	* [[dtAnimBestPractices\|dtAnim]]		* [[dtAnimBestPractices\|dtAnim]]
		+	* [[StyleGuide\|Coding Style Guide]]
		+	* [[CodingPractices\|Coding Practices]]