Kernel Class Reference
This reference page is linked to from the following overview topics: Application-Level Functionality, Menu Customization, Logging and Debugging Functions, Mudbox Scenes, Event Handling, File Event Handling, Writing a File Event Handler Plug-in, System Events, Miscellaneous Utilities, Instantiating Classes and Plug-ins.
Detailed Description
The main API access point to Mudbox, contains low level functions and data.
There is exactly one Kernel object, you use the Kernel() global function to access it.
#include <kernel.h>
Public Member Functions |
|
| Kernel (void) | |
| Constructor. There is exactly one kernel in
Mudbox, so you should never try to create one. |
|
| void | Log (const QString &sMessage) |
| Writes a message to Mudbox's internal log.
|
|
| void | LogMemoryStatus (bool bCompact=true) |
| Logs the current memory status. For
debugging purposes only. |
|
| void | LogMemoryBlocks (float fSizeLimit=0.01) |
| Logs current memory blocks (which are used
by the Store class). |
|
| bool | CreateNewScene () |
| Creates a new scene. |
|
| void | RecordCommand (const QString &sCommand) |
| Records a command to the mudbox automation
file. |
|
| class Scene * | CreateDefaultScene (void) |
| Creates a default mudbox scene and returns
it. |
|
| const ClassDesc * | PreferredDescendant (const ClassDesc *pClass) const |
| Returns the 'preferred descendant' of a
public interface, which must be used to create instances. |
|
| Node * | CreateClassInstance (const ClassDesc *pClass) const |
| Creates an instance of the preferred
descendant of an interface class. |
|
| Image * | LoadImage (const QString &sFileName, bool tiled=false) const |
| Creates a new image instance, loads a file
to it, and returns the pointer. |
|
| void | GLCheckError (const char *sSourceFileName, const char *sFunctionName, unsigned int iLine) const |
| Checks to see if there was an OpenGL error,
and writes it to the mudbox log. Used for debugging. |
|
| void | GLCheckStates (const char *sSourceFileName, const char *sFunctionName, unsigned int iLine) const |
| Checks if the opengl states are all set to
their default values, and writes the result to the Mudbox log. Used
for debugging. |
|
| void | Redraw (void) |
| Forces a full refresh of the 3d viewport.
|
|
| class Scene * | Scene (void) const |
| Returns a pointer to the current scene.
|
|
| mudbox::Preferences * | Preferences (void) const |
| Returns a pointer to the preferences.
|
|
| class mudbox::Interface * | Interface (void) const |
| Returns a pointer to the interface. |
|
| class Statistics * | Statistics (void) const |
| Returns a pointer to the program statistics.
|
|
| class ViewPort * | ViewPort (void) const |
| Returns a pointer to the current viewport.
|
|
| QString | MudboxVersionName (void) const |
| Returns a QString containing the version name of
the application. |
|
| void | RegisterWindowPlugin (WindowPlugin *plugin) const |
| Registers the Mudbox Community web browser.
|
|
| mudbox::TrayAccessor * | TrayAccessor (void) const |
| Returns a pointer to the tray accessor.
|
|
| bool | ExtractArchiveFile (QString sArchiveFilePath, QString sDestPath) |
| Extracts an archived file to destination.
|
|
| bool | CreateArchiveFile (QString sArchiveFilePath, QStringList files) |
| QString | DataDirectory (void) const |
| Returns the path to the data directory set
by the user. |
|
| QString | ApplicationDirectory (void) const |
| Returns the path to where the Mudbox
application is installed. |
|
| QString | ProjectFilesDirectory (void) const |
| Returns the path of the project files.
|
|
| QString | SafeWritableDirectory (void) const |
| Returns the root path to where the
application can safely write files. |
|
| QString | PluginDirectory (const QString &pluginName) const |
| Returns the path from which the specified
plugin was loaded. |
|
| bool | IsTestModeOn (void) const |
| Returns true if the application is in
testing mode (i.e. |
|
| bool | IsBetaVersion (void) const |
| Returns true if the application is a
beta/alpha version. |
|
| Image * | ExtractUnprojectedTextures (const QString &sChannel, int iWidth, int iHeight, enum Image::Format fmt=Image::e8integer, bool bTiledImg=false, bool allLayers=false) |
| Creates a 4 channel image containing the
unprojected textures of the scene using the current camera position
and settings. |
|
| Image * | ExtractUnprojectedTextures (int iWidth, int iHeight, enum Image::Format fmt=Image::e8integer, bool bTiledImg=false, bool allLayers=false) |
| Image * | ExtractShadingMap (int iWidth, int iHeight, enum Image::Format fmt=Image::e8integer, bool bTiledImg=false) |
| Creates a 4 channel image containing the
shading of the scene using the current camera position and
settings. |
|
| class XRef * | XRef () const |
| Returns the xref resolver used by the
application. |
|
| void | ReportVideoMemoryUsage (qint64 iSize) |
| Informs the kernel of video memory usage
changes. |
|
| qint64 | VideoMemoryUsage (void) const |
| Returns the total amount of video memory
currently in use in bytes. |
|
| qint64 | TotalVideoMemory (void) const |
| Returns the total amount of video memory
detected in the system, in bytes. |
|
| bool | DoOperation (Operation *pOp, bool bMerge=false) |
| This function executes an operation and
makes it possible to undo/redo the operation later. |
|
| const QList< class ImageIOHandler * > & |
ExternalImageIOHandlers () |
| void | FlushUndoQueue () |
| This function flushes the undo/redo queue.
|
|
| QString | TriggerFileEvent (FileEventNotifier::Type eType, const QString &sFileName) const |
| Trigger a file event. |
|
Public Attributes |
|
| astring | NextCommand |
| This attribute always contains the next
command. Plugins can link their own attribute to this one, and can
process commands this way. See RecordCommand().
|
|
| aevent | StrokeBeginEvent |
| This event is triggered when a new stroke is
started. See the class EventGate
for more details. |
|
| aevent | StrokeEndEvent |
| This event is triggered when a stroke has
ended. See the class EventGate
for more details. |
|
| aevent | TangentMirrorUpdateEvent |
| This event is triggered when tangent mirror
information is updated. |
|
| aevent | LowMemoryEvent |
| This event is triggered when the memory
status gets critical. |
|
| aevent | RestoreMemoryEvent |
| This event is triggered when memory status
is no longer critical. |
|
| aevent | PostUndoRedoEvent |
| This event is triggered after an undo or
redo operation is completed. |
|
| aptr< FileEventNotifier > | FileEvent |
| This is a pointer to the latest file event.
|
|
| aevent | ScenePreDeletedEvent |
| This event is triggered before a scene is
going to be deleted. |
|
Constructor & Destructor Documentation
| Kernel | ( | void | ) |
Constructor. There is exactly one kernel in Mudbox, so you should never try to create one.
Member Function Documentation
| void Log | ( | const QString & | sMessage | ) |
Writes a message to Mudbox's internal log.
The log can be viewed inside Mudbox in the "log" view, or by readin the mudbox.log file written by the application. (located at your documents/Mudbox/2009/data/Logs/mudbox.log on windows)
- Examples:
- PLYImport/Importer.cpp.
| void LogMemoryStatus | ( | bool | bCompact = true |
) |
Logs the current memory status. For debugging purposes only.
- Parameters:
-
[in] bCompact If true, write the status in a more compact form.
| void LogMemoryBlocks | ( | float | fSizeLimit = 0.01 |
) |
Logs current memory blocks (which are used by the Store class).
Blocks smaller than fSizeLimit*(largest block size) will not be logged. This call is mostly used to detect memory leaks.
- Parameters:
-
[in] fSizeLimit Specifies the minimum size of block that will be logged (this value times the largest block)
| bool CreateNewScene | ( | ) |
Creates a new scene.
If the current scene has been modified since it was opened, the user will be prompted to save it before it is replaced by the new scene. If the user chooses to cancel, this will return false. Otherwise this method will return true.
| void RecordCommand | ( | const QString & | sCommand | ) |
Records a command to the mudbox automation file.
As commands are executed in Mudbox, it records them into an automation file so that they can be played back later, usually for testing or debugging purposes. If you want your plugin actions to be recorded, call this method to record what it did. The format of this recordins should be a unique name for the command, followed by a list of arguments.
Note: this method takes the same arguments as standard printf, making it easy to specify arguments in your call.
If you record your plugin commands, then you also need to be able to play them back from your recording. To do this, define a variable of type astring in your plugin, and connect it to the m_sNextCommand variable of the Kernel, which always contains the string value of the next command to be performed. This connection is done like this:
Once you have done this, myNextCommand will change every time the variable in the Kernel changes, and you can capture that even to see if it is your command string. If it is, you run the command like this:
void myClass::OnNodeEvent( const Attribute &cAttribute, NodeEventType eType )
{
if ( eType == etValueChanged && cAttribute == myNextCommand )
{
// get the first word in the command
String sOperation = myNextCommand.Value().Section( ' ', 0 );
if ( sOperation == "myCommandName" ){
...get arguments and process your command here
| class Scene* CreateDefaultScene | ( | void | ) |
Creates a default mudbox scene and returns it.
Returns the 'preferred descendant' of a public interface, which must be used to create instances.
In the mudbox SDK you will find lots of interfaces defined without any functionality, such as Texture and Image. Plugins can implement these interfaces by defining their own classes inherited from an SDK interface. When the functionality is needed somewhere, then this function can tell you what the best available implementation is. You can then create one instance of that class and access the functionality you need. You should use the CreateInstance() global templated function to create those object. (It uses PreferredDescendant() internally, but provides a more comfortable way to access those functionalities.)
Creates an instance of the preferred descendant of an interface class.
See PreferredDescendant() for more details. We recommend using the CreateInstance() global function instead of this.
Creates a new image instance, loads a file to it, and returns the pointer.
It is the responsibility of the caller to delete the returned Image.
/b Note: This function will be removed from future releases of the SDK.
- Parameters:
-
[in] sFileName Path of the image file to be opened. [in] tiled true if the image is to be versioned and tiled.
| void GLCheckError | ( | const char * | sSourceFileName, |
| const char * | sFunctionName, | ||
| unsigned int | iLine | ||
| ) | const |
Checks to see if there was an OpenGL error, and writes it to the mudbox log. Used for debugging.
- Parameters:
-
[in] sSourceFileName The name of the file where this is being called [in] sFunctionName The name of the function from which this is being called [in] iLine The line number where this is being called
| void GLCheckStates | ( | const char * | sSourceFileName, |
| const char * | sFunctionName, | ||
| unsigned int | iLine | ||
| ) | const |
Checks if the opengl states are all set to their default values, and writes the result to the Mudbox log. Used for debugging.
- Parameters:
-
[in] sSourceFileName The name of the file where this is being called [in] sFunctionName The name of the function from which this is being called [in] iLine The line number where this is being called
| void Redraw | ( | void | ) |
Forces a full refresh of the 3d viewport.
This function is obsolete, use ViewPort::Redraw instead.
Returns a pointer to the current scene.
| mudbox::Preferences* Preferences | ( | void | ) | const |
Returns a pointer to the preferences.
| class mudbox::Interface* Interface | ( | void | ) | const |
Returns a pointer to the interface.
| class Statistics* Statistics | ( | void | ) | const |
Returns a pointer to the program statistics.
Returns a pointer to the current viewport.
- Examples:
- MeshBuilder/MeshBuilder.cpp.
| QString MudboxVersionName | ( | void | ) | const |
Returns a QString containing the version name of the application.
| void RegisterWindowPlugin | ( | WindowPlugin * | plugin | ) | const |
Registers the Mudbox Community web browser.
| mudbox::TrayAccessor* TrayAccessor | ( | void | ) | const |
Returns a pointer to the tray accessor.
Extracts an archived file to destination.
| bool CreateArchiveFile | ( | QString | sArchiveFilePath, |
| QStringList | files | ||
| ) |
| QString DataDirectory | ( | void | ) | const |
Returns the path to the data directory set by the user.
| QString ApplicationDirectory | ( | void | ) | const |
Returns the path to where the Mudbox application is installed.
| QString ProjectFilesDirectory | ( | void | ) | const |
Returns the path of the project files.
| QString SafeWritableDirectory | ( | void | ) | const |
Returns the root path to where the application can safely write files.
Returns the path from which the specified plugin was loaded.
| bool IsTestModeOn | ( | void | ) | const |
Returns true if the application is in testing mode (i.e.
was started with the -test command line parameter).
| bool IsBetaVersion | ( | void | ) | const |
Returns true if the application is a beta/alpha version.
| Image* ExtractUnprojectedTextures | ( | const QString & | sChannel, |
| int | iWidth, | ||
| int | iHeight, | ||
| enum Image::Format | fmt =
Image::e8integer, |
||
| bool | bTiledImg = false, |
||
| bool | allLayers =
false |
||
| ) |
Creates a 4 channel image containing the unprojected textures of the scene using the current camera position and settings.
The image will be rendered at the specified size, or if the specified width and height are 0, it will use the current viewport size. currently only 8 bit images are supported by this operation Resulting images currently must be untiled.
- Parameters:
-
[in] sChannel the name of the channel to render [in] iWidth The width of the rendering in pixels. Set to 0 to use current screen size. [in] iHeight The height of the rendering in pixels. Set to 0 to use current screen size. [in] fmt Desired image format. Currently must be e8integer [in] bTiledImg hint -- true if the resulting image is to be tiled, false if contiguous. [in] allLayers all the layers, or only the current one
| Image* ExtractUnprojectedTextures | ( | int | iWidth, |
| int | iHeight, | ||
| enum Image::Format | fmt =
Image::e8integer, |
||
| bool | bTiledImg = false, |
||
| bool | allLayers =
false |
||
| ) |
- Parameters:
-
[in] iWidth The width of the rendering in pixels. Set to 0 to use current screen size. [in] iHeight The height of the rendering in pixels. Set to 0 to use current screen size. [in] fmt Desired image format. Currently must be e8integer [in] bTiledImg hint -- true if the resulting image is to be tiled, false if contiguous. [in] allLayers all the layers, or only the current one
| Image* ExtractShadingMap | ( | int | iWidth, |
| int | iHeight, | ||
| enum Image::Format | fmt =
Image::e8integer, |
||
| bool | bTiledImg =
false |
||
| ) |
Creates a 4 channel image containing the shading of the scene using the current camera position and settings.
The image will be rendered at the specified size, or if the specified width and height are 0, it will use the current viewport size. The result of this image, blended over a flat shaded version of the scene will appear as though the shading and shadowing were turned on. currently only 8 bit images are supported by this operation Resulting images currently must be untiled.
- Parameters:
-
[in] iWidth The width of the rendering in pixels. Set to 0 to use current screen size. [in] iHeight The height of the rendering in pixels. Set to 0 to use current screen size. [in] fmt Desired image format. Currently must be e8integer [in] bTiledImg hint -- true if the resulting image is to be tiled, false if contiguous.
Returns the xref resolver used by the application.
| void ReportVideoMemoryUsage | ( | qint64 | iSize | ) |
Informs the kernel of video memory usage changes.
When a plugin allocates or frees video memory, it should call this function to inform mudbox about the change. If it doesn't call this function, then Mudbox will not know how much video memory is available. This information is used to optimize some operations. When video memory is deallocated, the iSize parameter should be negative.
- Parameters:
-
[in] iSize The amount of video memory memory used (positive numbers) or released (negative numbers) in bytes
| qint64 VideoMemoryUsage | ( | void | ) | const |
Returns the total amount of video memory currently in use in bytes.
| qint64 TotalVideoMemory | ( | void | ) | const |
Returns the total amount of video memory detected in the system, in bytes.
| bool DoOperation | ( | Operation * | pOp, |
| bool | bMerge =
false |
||
| ) |
This function executes an operation and makes it possible to undo/redo the operation later.
If a plugin wants an operation to be undoable, it must execute the operation using this function call.
- See also:
- mudbox::Operation
- Parameters:
-
[in] pOp Address of the operation which has to be executed. [in] bMerge When this parameter is true, this operation will be undone/redone in a common step with the previous one.
| const QList<class ImageIOHandler *>& ExternalImageIOHandlers | ( | ) |
| void FlushUndoQueue | ( | ) |
This function flushes the undo/redo queue.
You may want to call this function if you do something not undoable and don't want to go back.
Trigger a file event.
The returned filepath can be different than the one passed as parameter.
The mudbox kernel triggers file events every time when it: 1. About to open a file for reading 2. About to open a file for writing 3. Read a file 4. Wrote a file 5. About to let the user browse for a file to read 6. About to let the user browse for a file to write When a file operation happens in Mudbox, the events listed above are triggered. If your plugins reads or writes files, they should trigger the appropriate events by calling this method. The returned string is the filename, which is usually the same as the passed sFileName, but it might be modified by an entity that intercepted the file event.
- Parameters:
-
[in] eType One of FileEventNotifier::typeBrowseForRead, FileEventNotifier::typeBrowseForWrite, FileEventNotifier::typePreRead, FileEventNotifier::typePostRead, FileEventNotifier::typePreWrite or FileEventNotifier::typePostWrite [in] sFileName The filepath that is the intended target of the operation. This can be changed by whoever intercepts the event.
Member Data Documentation
This attribute always contains the next command. Plugins can link their own attribute to this one, and can process commands this way. See RecordCommand().
This event is triggered when a new stroke is started. See the class EventGate for more details.
This event is triggered when a stroke has ended. See the class EventGate for more details.
This event is triggered when tangent mirror information is updated.
This event is triggered when the memory status gets critical.
Plugins should deallocate temporary buffers to help the situation. See the class EventGate for more details.
This event is triggered when memory status is no longer critical.
Plugins can allocate their temporary buffers and fill them with data if they wish. See the class EventGate for more details.
This event is triggered after an undo or redo operation is completed.
aptr<FileEventNotifier>
FileEvent
[mutable] |
This is a pointer to the latest file event.
Plugins can use this pointer to catch file event. When a new file event is triggered, this pointer will change its value to the new file event. Plugins can also have their own pointer with the same type. At startup they can connect their pointer to this pointer in kernel by calling the Connect() function on their pointer. This means that when the FileEvent pointer in kernel changes, their own pointer will also change. They can then catch this in their OnNodeEvent() function. Using this pointer to anything else than connecting an own pointer to it is forbidden.
This event is triggered before a scene is going to be deleted.
The documentation for this class was generated from the following file:
- Mudbox/kernel.h
