
//**************************************************************************/
// Copyright (c) 2008 Autodesk, Inc.
// All rights reserved.
//
// Use of this software is subject to the terms of the Autodesk license
// agreement provided at the time of installation or download, or which
// otherwise accompanies this software in either electronic or hard copy form.
//
//**************************************************************************/
// DESCRIPTION:
// CREATED: October 2008
//**************************************************************************/

namespace mudbox {

/// \brief This class is the base class for plugins that import geometry into Mudbox. 
/// 
/// To create a new importer plugin, derive your own class from this one and implement it. Use the
/// DECLARE_CLASS and IMPLEMENT_CLASS macros to provide information about your importer to Mudbox.
/// Once this is done, Mudbox will know enough about your class to use it. When
/// the user wants to import a new file, mudbox will show the user a list of files filtered by
/// the extension specified by your derived class,
/// and if the user chooses one of those files, mudbox will instantiate your class and use it to import the file.
/// When instantiated, the Importer will create it's own private scene. Override the Import() method to attach
/// translated data items to the Importer's scene. Once the Import() call is complete, Mudbox will merge data from
/// the importer's scene into the current scene.
///
/// At this time, meshes, materials and cameras are supported for import.
class MBDLL_DECL Importer : public Node
{
	DECLARE_CLASS;

	/// Mudbox will destroy the importer after the import process is complete.
	/// The importer's destructor will destroy the importer's private scene.
	/// Add your own destructor to cleanup any temporary data once the import is complete.
	virtual ~Importer();

	/// \brief Returns the file extension read by this importer.
	///
	/// Override this function to make it return the extention of the file type you wish to read, for example: "ply".
	/// At this time only a single extension is supported.
	virtual QString Extension( void );
	
	/// \brief Returns a small text description of your file type.
	///
	/// Override this function to make it return return a small description which will appear in the browse file dialog.
	virtual QString Description( void );

	/// \brief Imports the data from the file and holds it locally.
	///
	/// This method will be called by Mudbox when it is time to import the data. Override this method to attach the loaded information 
	/// to the importer's private scene that is returned by SceneCreatedByImporter(). It is probably easiest
	/// to store the data internally as Mesh objects.
	virtual void Import(
		const QString &sFileName		//< [in] The full path to the file to be imported
		);

	/// \brief Returns the scene that was created by the importer
	///
	/// This function is called by Mudbox after Import(). Elements in this scene are merged
	/// into the Mudbox scene. Attach imported mesh data to this scene. 
	/// The Importer class owns this Scene and is responsible for its memory.
	/// This always returns a non-null value.
	virtual Scene* SceneCreatedByImporter();

	/// \brief Convenience method importers can use to add meshes to their imported scenes.
	///
	/// You can call this from your Import() method.
	void AddMesh( Mesh* pMesh );

protected:

	/// \brief Do not use the constructor directly.
	///
	/// use \a CreateInstances instead.
	Importer();

	/// \brief Do not access this variable directly.
	///
	/// use SceneCreatedByImporter() instead.
	aptr<Scene> m_pScene;
};

/// \brief This class is the base class for plugins that export mesh geometry from Mudbox. 
/// 
/// To create a new exporter plugin, derive your own class from this one and implement it. Use the
/// DECLARE_CLASS and IMPLEMENT_CLASS macros to provide information about your exporter to Mudbox.
/// Once this is done, Mudbox will know enough about your class to use it. When
/// the user wants to export a new file, mudbox will recognize your specified extension.
///
/// At this time, only mesh objects are supported.
/// During an export operation, Mudbox first calls SetMeshCount() and SetMesh()
/// to specify which meshes should be exported. Finally, it calls the Export() function to do the work.
class MBDLL_DECL Exporter : public Node
{
	DECLARE_CLASS;

	/// \brief Returns the file extension written by this exporter.
	///
	/// Override this function to make it return the extention of the file type you write, for example: "ply".
	/// At this time only a single extension is supported.
	virtual QString Extension( void );
	
	/// \brief Returns a small text description of your file type.
	///
	/// Override this function to make it return return a small description which will appear in the browse dialog.
	virtual QString Description( void );

	/// \brief Export the specified meshes.
	///
	/// This function will be called after Mudbox calls SetMeshCount() and SetMesh() to provide your class with
	/// all the needed mesh data.  Override this method to make it do the actual writing of your file type.
	virtual void Export(
		const QString &sFileName	///< [in] The path of the file to be written
		);

	/// Tells the exporter how many meshes are to be exported.
	virtual void SetMeshCount(
		unsigned int iMeshCount		///< [in] Number of meshes that will be exported
		);
		
	/// \brief Specifies which mesh(es) should be exported.  This is called once per mesh, after Mudbox
	/// has called SetMeshCount().  In your overridden class, you do not need to store all the Mesh data.
	/// Instead, you can just store pointers to the appropriate meshes and then access their data in the
	/// Export() method.
	virtual void SetMesh(
		unsigned int iIndex,	///< [in] Index of the specified mesh
		const Mesh *pMesh		///< [in] the specified mesh
		);
};

}; // end of namespace mudbox
