scene Class Reference

The scene JavaScript global object. Retrieve and set global scene attributes, like the aspect ratio of the cells in the scene grid. More...

Public Slots

int currentVersion ()
 Returns the ID of the current version. More...
 
String currentVersionName ()
 Returns the name or the number of the current scene version. More...
 
String currentEnvironment ()
 Returns the name of the current environment. More...
 
String currentEnvironmentPath ()
 Returns the path of the current environment. More...
 
String currentJob ()
 Returns the name of the current job. More...
 
String currentJobPath ()
 Returns the path of the current job. More...
 
String currentScene ()
 Returns the name of the current scene. More...
 
String currentProjectPath ()
 Returns the current project path. More...
 
String currentProjectPathRemapped ()
 For windows, returns the remapped path. More...
 
String tempProjectPath ()
 Returns the temporary project path. More...
 
String tempProjectPathRemapped ()
 For windows, returns the remapped temporary project path. More...
 
Undo / Redo

Functions will generate only one Undo/Redo entry if sandwiched by these two functions.

void beginUndoRedoAccum (String commandName)
 This function starts the accumulation of all of the functions between it and the endUndoRedoAccum function as one command that will appear in the undo/redo list. If you do not use this function with endUndoRedoAccum, each function in the script generates a separate undo/redo entry. More...
 
void endUndoRedoAccum ()
 This function ends the accumulation all of the functions between it and the beginUndoRedoAccum function as one command that will appear in the undo/redo list. If you do not use this function with beginUndoRedoAccum, each function in the script generates a separate undo/redo entry. More...
 
void cancelUndoRedoAccum ()
 This function cancels the accumulation of undo/redo commands. No command will be added to the undo/redo list and all commands that have already been executed will be rolled-back (undone). More...
 
void undo (int depth=1)
 Undoes the last n operations. If n is not specified, it will be 1. More...
 
void redo (int depth=1)
 Redoes the last n operations. If n is not specified, it will be 1. More...
 
void clearHistory ()
 Clears the command history. More...
 
Global Scene Data.
double unitsAspectRatioX ()
 Returns the X value of the aspect ratio of the cells in the scene grid. More...
 
double unitsAspectRatioY ()
 Returns the Y value of the aspect ratio of the cells in the scene grid. More...
 
int numberOfUnitsX ()
 Returns the number of units in the X axis of the scene grid. More...
 
int numberOfUnitsY ()
 Returns the number of units in the Y axis of the scene grid. More...
 
int numberOfUnitsZ ()
 Returns the number of units in the Z axis of the scene grid. More...
 
int coordAtCenterX ()
 Returns the X value of the centre coordinate of the scene grid. More...
 
int coordAtCenterY ()
 Returns the Y value of the centre coordinate of the scene grid. More...
 
int currentResolutionX ()
 Returns the X value of the current preview resolution. More...
 
int currentResolutionY ()
 Returns the Y value of the current preview resolution. More...
 
String defaultResolutionName ()
 Returns the default resolution name. More...
 
int defaultResolutionX ()
 Returns the X value of the default resolution. More...
 
int defaultResolutionY ()
 Returns the Y value of the default resolution. More...
 
double defaultResolutionFOV ()
 Returns the default resolution field of view (FOV). The default FOV is a global scene parameter. More...
 
StringList namedResolutions ()
 Returns the list of known resolutions. More...
 
int namedResolutionX (String name)
 Returns the X value of the named resolution. For example, when the named resolution is 720x540 pixels this function will return 720. More...
 
int namedResolutionY (String name)
 Returns the Y value of the named resolution. For example, when the named resolution is 720x540 pixels this function will return 540. More...
 
double getFrameRate ()
 Returns the frame rate, as frames per second. More...
 
void setDefaultTexturePixelDensityforVectorDrawings (double &normalizedDensity)
 Changes the default texture pixel density for new Vector Drawings. More...
 
void setDefaultTexturePixelDensityforBitmapDrawings (double &normalizedDensity)
 Changes the default texture pixel density for new Bitmap Drawings. More...
 

Saving functions

bool isDirty ()
 Tells if the scene has been modified since its last save. More...
 
bool hasBeenDirty ()
 Returns true if the scene was ever modified. More...
 
bool saveAll ()
 Performs the "save all" command. Effectively, this saves the entire project and all modified files. More...
 
bool saveAsNewVersion (String &name, bool markAsDefault)
 Saves the project as a new version. More...
 
bool saveAs (String &pathname)
 Save the current project to the specified folder or sbpz file. More...
 

Global Scene Edition.

bool setUnitsAspectRatio (double x, double y)
 Sets the aspect ratio of the scene. The scene's final aspect ratio will be: X * numberOfUnitsX()/Y * numberOfUnitsY(). More...
 
bool setNumberOfUnits (int x, int y, int z)
 Sets the number of X, Y, and Z units in the scene grid. More...
 
bool setCoordAtCenter (int x, int y)
 Sets the value of the centre (X, Y) coordinates. More...
 
bool setDefaultResolution (int x, int y, double fov)
 Sets the default scene resolution and field of view. More...
 
bool setDefaultResolutionName (String name)
 This function sets the default scene resolution name. More...
 
bool setFrameRate (double frameRate)
 This function set the default frame rate of the project. The frame rate is expressed as frames per second. Typical value is 12, 24 or 30. More...
 
QObjectgetCameraMatrix (int frame)
 Returns the model matrix for the default camera. More...
 
QObjecttoOGL (QObject *pointOrVector)
 Converts a field coordinate into an OGL coordinate. More...
 
double toOGLX (double fieldX)
 Converts the X-value of a field coordinate to the X-value of an OpenGL coordinate. More...
 
double toOGLY (double fieldY)
 Converts the Y-value of a field coordinate to the Y-value of an OpenGL coordinate. More...
 
double toOGLZ (double fieldZ)
 Converts the Z-value of a field coordinate to the Z-value of an OpenGL coordinate. More...
 
QObjectfromOGL (QObject *pointOrVector)
 Converts an OGL coordinate into a field coordinate. More...
 
double fromOGLX (double oglX)
 Converts the X-value of an OpenGL coordinate to the X-value of a field coordinate. More...
 
double fromOGLY (double oglY)
 Converts the Y-value of an OpenGL coordinate to the Y-value of a field coordinate. More...
 
double fromOGLZ (double oglZ)
 Converts the Z-value of an OpenGL coordinate to the Z-value of a field coordinate. More...
 
String getDefaultDisplay ()
 Retrieves the default display set in the current scene. More...
 
void closeScene ()
 Closes the current scene. More...
 
void closeSceneAndExit ()
 Closes the current scene and exits. More...
 
bool closeSceneAndOpenOffline (String &filePath)
 Closes the current scene and open the scene specified by it's file path. More...
 
StringList getMissingPalettes (bool unrecovered, bool recoveredNotYetSaved)
 Returns all palettes that were either unrecovered or recovered but not yet saved, depending on the arguments of the function. More...
 
QScriptValue metadatas ()
 Return the list of metadatas for the current scene. More...
 
QScriptValue metadata (String &name, String &type=QNTR("string"))
 Return a metadata object corresponding to the given name and type. More...
 
void setMetadata (QScriptValue &meta)
 Either inserts a new metadata object or sets the value of an existing metadata object. More...
 
bool removeMetadata (QScriptValue &meta)
 Removes a metadata object from the list of metadata objects. More...
 

Detailed Description

The scene JavaScript global object. Retrieve and set global scene attributes, like the aspect ratio of the cells in the scene grid.

function setScene()
{
// Sets the beginning of the undo/redo command wrapper
scene.beginUndoRedoAccum("Set Scene");
// Sets the aspect ratio of the scene to 4, 3
// Sets the number of units in the scene
scene.setNumberOfUnits(1200, 900, 12);
// Sets the value of the center coordinate
scene.setCoordAtCenter(5000, 5000);
// Terminates the undo/redo command wrapper
}

Member Function Documentation

◆ beginUndoRedoAccum

void scene::beginUndoRedoAccum ( String  commandName)
slot

This function starts the accumulation of all of the functions between it and the endUndoRedoAccum function as one command that will appear in the undo/redo list. If you do not use this function with endUndoRedoAccum, each function in the script generates a separate undo/redo entry.

Parameters
commandName: The name of the command to be added to the undo/redo list.

◆ cancelUndoRedoAccum

void scene::cancelUndoRedoAccum ( )
slot

This function cancels the accumulation of undo/redo commands. No command will be added to the undo/redo list and all commands that have already been executed will be rolled-back (undone).

◆ clearHistory

void scene::clearHistory ( )
slot

Clears the command history.

◆ closeScene

void scene::closeScene ( )
slot

Closes the current scene.

Exiting functions Anyone of these is final and absolute. Nothing in the script will be executed after these calls.

◆ closeSceneAndExit

void scene::closeSceneAndExit ( )
slot

Closes the current scene and exits.

◆ closeSceneAndOpenOffline

bool scene::closeSceneAndOpenOffline ( String &  filePath)
slot

Closes the current scene and open the scene specified by it's file path.

Parameters
filePath: The full path to the file to open.
Returns
Returns true if the scene is successfully closed, and the specified one opened.

◆ coordAtCenterX

int scene::coordAtCenterX ( )
slot

Returns the X value of the centre coordinate of the scene grid.

Returns
The X value of the centre coordinate of the scene grid.

◆ coordAtCenterY

int scene::coordAtCenterY ( )
slot

Returns the Y value of the centre coordinate of the scene grid.

Returns
The Y value of the centre coordinate of the scene grid.

◆ currentEnvironment

String scene::currentEnvironment ( )
slot

Returns the name of the current environment.

Returns
The name of the current environment.

◆ currentEnvironmentPath

String scene::currentEnvironmentPath ( )
slot

Returns the path of the current environment.

Returns
The path of the current environemnt.

◆ currentJob

String scene::currentJob ( )
slot

Returns the name of the current job.

Returns
The name of the current job.

◆ currentJobPath

String scene::currentJobPath ( )
slot

Returns the path of the current job.

Returns
The path of the current job.

◆ currentProjectPath

String scene::currentProjectPath ( )
slot

Returns the current project path.

Returns
The current project path.

◆ currentProjectPathRemapped

String scene::currentProjectPathRemapped ( )
slot

For windows, returns the remapped path.

Returns
The remapped path.

◆ currentResolutionX

int scene::currentResolutionX ( )
slot

Returns the X value of the current preview resolution.

For example, when the current resolution is 720x540 pixels this function will return 720.

Returns
The X value of the current preview resolution.

◆ currentResolutionY

int scene::currentResolutionY ( )
slot

Returns the Y value of the current preview resolution.

For example, when the current resolution is 720x540 pixels this function will return 540.

Returns
The Y value of the current preview resolution.

◆ currentScene

String scene::currentScene ( )
slot

Returns the name of the current scene.

Returns
The name of the current scene.

◆ currentVersion

int scene::currentVersion ( )
slot

Returns the ID of the current version.

Returns
The ID of the current version.

◆ currentVersionName

String scene::currentVersionName ( )
slot

Returns the name or the number of the current scene version.

Returns
The name or the number of the current scene version.

◆ defaultResolutionFOV

double scene::defaultResolutionFOV ( )
slot

Returns the default resolution field of view (FOV). The default FOV is a global scene parameter.

Returns
The default resolution field of view (FOV).

◆ defaultResolutionName

String scene::defaultResolutionName ( )
slot

Returns the default resolution name.

The resolution name is a global parameter saved with the project. It may be empty when the project is used as a custom resolution, which is not one of the pre-defined resolutions.

Returns
The default resolution name.

◆ defaultResolutionX

int scene::defaultResolutionX ( )
slot

Returns the X value of the default resolution.

This resolution is a global parameter saved with the project, not the current preview resolution. For example, when the default scene resolution is 720x540 pixels this function will return 720.

Returns
The X value of the default resolution.

◆ defaultResolutionY

int scene::defaultResolutionY ( )
slot

Returns the Y value of the default resolution.

This resolution is a global parameter saved with the project, not the current preview resolution. For example, when the default scene resolution is 720x540 pixels this function will return 540.

Returns
The Y value of the default resolution.

◆ endUndoRedoAccum

void scene::endUndoRedoAccum ( )
slot

This function ends the accumulation all of the functions between it and the beginUndoRedoAccum function as one command that will appear in the undo/redo list. If you do not use this function with beginUndoRedoAccum, each function in the script generates a separate undo/redo entry.

◆ fromOGL

QObject* scene::fromOGL ( QObject pointOrVector)
slot

Converts an OGL coordinate into a field coordinate.

Parameters
pointOrVectorcan be either a 2D point or a 3D point or a vector object.
Returns
The converted field coordinate.

◆ fromOGLX

double scene::fromOGLX ( double  oglX)
slot

Converts the X-value of an OpenGL coordinate to the X-value of a field coordinate.

Parameters
oglX: The X-value of an OpenGL coordinate.
Returns
The X-value of a field coordinate.

◆ fromOGLY

double scene::fromOGLY ( double  oglY)
slot

Converts the Y-value of an OpenGL coordinate to the Y-value of a field coordinate.

Parameters
oglY: The Y-value of an OpenGL coordinate.
Returns
The Y-value of a field coordinate.

◆ fromOGLZ

double scene::fromOGLZ ( double  oglZ)
slot

Converts the Z-value of an OpenGL coordinate to the Z-value of a field coordinate.

Parameters
oglZ: The Z-value of an OpenGL coordinate.
Returns
The Z-value of a field coordinate.

◆ getCameraMatrix

QObject* scene::getCameraMatrix ( int  frame)
slot

Returns the model matrix for the default camera.

Parameters
frame: The frame to retrieve the camera matrix at.
Returns
The model matrix for the default camera.

◆ getDefaultDisplay

String scene::getDefaultDisplay ( )
slot

Retrieves the default display set in the current scene.

Returns
The default display set in the current scene.

◆ getFrameRate

double scene::getFrameRate ( )
slot

Returns the frame rate, as frames per second.

Returns
The frame rate, as frames per second.

◆ getMissingPalettes

StringList scene::getMissingPalettes ( bool  unrecovered,
bool  recoveredNotYetSaved 
)
slot

Returns all palettes that were either unrecovered or recovered but not yet saved, depending on the arguments of the function.

Parameters
unrecovered: Whether or not to return unrecovered palettes.
recoveredNotYetSaved: Whether or not to return recovered but not yet saved palettes.
Returns
Returns all palettes that were either unrecovered or recovered but not yet saved.

◆ hasBeenDirty

bool scene::hasBeenDirty ( )
slot

Returns true if the scene was ever modified.

It will return true even if the modifications have been saved.

Returns
True if the scene has been modified since it was loaded, false if it was never modified in this session.

◆ isDirty

bool scene::isDirty ( )
slot

Tells if the scene has been modified since its last save.

Returns
true if the scene has been modified since its last save.

◆ metadata

QScriptValue scene::metadata ( String &  name,
String &  type = QNTR("string") 
)
slot

Return a metadata object corresponding to the given name and type.

Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Harmony Premium",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Parameters
name: The name of the metadata object.
type: The metadata type.
Returns
A metadata object.

◆ metadatas

QScriptValue scene::metadatas ( )
slot

Return the list of metadatas for the current scene.

This method returns an array of javascript objects where each object represent a single metadata object. Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Harmony Premium",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Returns
An array of metadata objects.

◆ namedResolutions

StringList scene::namedResolutions ( )
slot

Returns the list of known resolutions.

Returns
The list of the known resolutions.

◆ namedResolutionX

int scene::namedResolutionX ( String  name)
slot

Returns the X value of the named resolution. For example, when the named resolution is 720x540 pixels this function will return 720.

Parameters
name: The name of the resolution to get the value from.
Returns
The X value of the named resolution.

◆ namedResolutionY

int scene::namedResolutionY ( String  name)
slot

Returns the Y value of the named resolution. For example, when the named resolution is 720x540 pixels this function will return 540.

Parameters
name: The name of the resolution to get the value from.
Returns
The Y value of the named resolution.

◆ numberOfUnitsX

int scene::numberOfUnitsX ( )
slot

Returns the number of units in the X axis of the scene grid.

Returns
The number of units in the X axis of the scene grid.

◆ numberOfUnitsY

int scene::numberOfUnitsY ( )
slot

Returns the number of units in the Y axis of the scene grid.

Returns
The number of units in the Y axis of the scene grid.

◆ numberOfUnitsZ

int scene::numberOfUnitsZ ( )
slot

Returns the number of units in the Z axis of the scene grid.

Returns
The number of units in the Z axis of the scene grid.

◆ redo

void scene::redo ( int  depth = 1)
slot

Redoes the last n operations. If n is not specified, it will be 1.

Parameters
depth: The number of operations to redo.

◆ removeMetadata

bool scene::removeMetadata ( QScriptValue &  meta)
slot

Removes a metadata object from the list of metadata objects.

Parameters
meta: A metadata object.
Returns
true if the metadata was successfully removed from the list.

◆ saveAll

bool scene::saveAll ( )
slot

Performs the "save all" command. Effectively, this saves the entire project and all modified files.

Returns
true if the project and files are successfully saved.

◆ saveAs()

bool scene::saveAs ( String &  pathname)

Save the current project to the specified folder or sbpz file.

Save the current project to the specified folder or sbpz file. The current project is updated to use that folder or sbpz file. Any error or message is reported using the standard error logger, user will see message popup. Cannot be use in batch mode.

Parameters
pathname: New folder of the project (ie: /Users/a_user/Documents/my_save_as_project ) or new sbpz file /Users/a_user/Documents/my_save_as_project.sbpz )
Returns
true if successfully saved the project.

◆ saveAsNewVersion

bool scene::saveAsNewVersion ( String &  name,
bool  markAsDefault 
)
slot

Saves the project as a new version.

Parameters
name: The name of the version.
markAsDefault: This is boolean to indicate to mark this version as the default version.
Returns
true if the project is successfully saved.

◆ setCoordAtCenter

bool scene::setCoordAtCenter ( int  x,
int  y 
)
slot

Sets the value of the centre (X, Y) coordinates.

Parameters
x: The value of the X coordinate at the centre of the grid.
y: The value of the Y coordinate at the centre of the grid.
Returns
true if the new centre coordinate is set.

◆ setDefaultResolution

bool scene::setDefaultResolution ( int  x,
int  y,
double  fov 
)
slot

Sets the default scene resolution and field of view.

Parameters
x: Set the X resolution for the scene in pixels.
y: Set the Y resolution for the scene in pixels.
fov: Set the field of view in degree. Typical value is 41.112.
Returns
true if the default resolution is set.

◆ setDefaultResolutionName

bool scene::setDefaultResolutionName ( String  name)
slot

This function sets the default scene resolution name.

Parameters
name: Set the current resolution preset name to this value.
Returns
true if the default resolution name is set.

◆ setDefaultTexturePixelDensityforBitmapDrawings

void scene::setDefaultTexturePixelDensityforBitmapDrawings ( double &  normalizedDensity)
slot

Changes the default texture pixel density for new Bitmap Drawings.

The example below uses scene.setDefaultTexturePixelDensityforBitmapDrawings() to reduce the scene settings' default pixel density for bitmap drawings to 20%.

Parameters
normalizedDensity: The new normalized default pixel density (1.0 = 100%)

◆ setDefaultTexturePixelDensityforVectorDrawings

void scene::setDefaultTexturePixelDensityforVectorDrawings ( double &  normalizedDensity)
slot

Changes the default texture pixel density for new Vector Drawings.

The example below uses scene.setDefaultTexturePixelDensityforVectorDrawings() to increase the scene settings' default pixel density for vector drawings to 300%.

Parameters
normalizedDensity: The new normalized default pixel density (1.0 = 100%)

◆ setFrameRate

bool scene::setFrameRate ( double  frameRate)
slot

This function set the default frame rate of the project. The frame rate is expressed as frames per second. Typical value is 12, 24 or 30.

Parameters
frameRate: The new frame rate.
Returns
true if the frame rate is set.

◆ setMetadata

void scene::setMetadata ( QScriptValue &  meta)
slot

Either inserts a new metadata object or sets the value of an existing metadata object.

If a metadata object already exist with the given name and type properties, then sets its value with the given value property. Otherwise, inserts a new metadata object with the given name, type(default is string), creator(default is executable), version(default is 1.0) and values properties. Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Harmony Premium",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Parameters
meta: A metadata object.

◆ setNumberOfUnits

bool scene::setNumberOfUnits ( int  x,
int  y,
int  z 
)
slot

Sets the number of X, Y, and Z units in the scene grid.

Parameters
x: The X value of the scene grid.
y: The Y value of the scene grid.
z: The Z value of the scene grid.
Returns
true if the new aspect ratio is successfully set.

◆ setUnitsAspectRatio

bool scene::setUnitsAspectRatio ( double  x,
double  y 
)
slot

Sets the aspect ratio of the scene. The scene's final aspect ratio will be: X * numberOfUnitsX()/Y * numberOfUnitsY().

Parameters
x: The X value of the new aspect ratio.
y: The Y value of the new aspect ratio.
Returns
true if the new aspect ratio is successfully set.

◆ tempProjectPath

String scene::tempProjectPath ( )
slot

Returns the temporary project path.

Returns
The temporary project path.

◆ tempProjectPathRemapped

String scene::tempProjectPathRemapped ( )
slot

For windows, returns the remapped temporary project path.

The remapped temporary project path.

◆ toOGL

QObject* scene::toOGL ( QObject pointOrVector)
slot

Converts a field coordinate into an OGL coordinate.

Parameters
pointOrVectorcan be either a 2D point or a 3D point or a vector object.
Returns
The converted OGL coordinate.

◆ toOGLX

double scene::toOGLX ( double  fieldX)
slot

Converts the X-value of a field coordinate to the X-value of an OpenGL coordinate.

Parameters
fieldX: The X-value of a field coordinate.
Returns
The X-value of an OpenGL coordinate.

◆ toOGLY

double scene::toOGLY ( double  fieldY)
slot

Converts the Y-value of a field coordinate to the Y-value of an OpenGL coordinate.

Parameters
fieldY: The Y-value of a field coordinate.
Returns
The Y-value of an OpenGL coordinate.

◆ toOGLZ

double scene::toOGLZ ( double  fieldZ)
slot

Converts the Z-value of a field coordinate to the Z-value of an OpenGL coordinate.

Parameters
fieldZ: The Z-value of a field coordinate.
Returns
The Z-value of an OpenGL coordinate.

◆ undo

void scene::undo ( int  depth = 1)
slot

Undoes the last n operations. If n is not specified, it will be 1.

Parameters
depth: The number of operations to undo.

◆ unitsAspectRatioX

double scene::unitsAspectRatioX ( )
slot

Returns the X value of the aspect ratio of the cells in the scene grid.

Returns
The X value of the aspect ratio of the cells in the scene grid.

◆ unitsAspectRatioY

double scene::unitsAspectRatioY ( )
slot

Returns the Y value of the aspect ratio of the cells in the scene grid.

Returns
The Y value of the aspect ratio of the cells in the scene grid.