Creation Platform 1.8.0-beta Release Notes

../_images/FE_logo_345_60.png
Creation Platform version 1.8.0-beta
Copyright (c) 2010-2017 Fabric Software Inc. All rights reserved.

Important Notes - Read Me First!

  • Creation Platform requires a video card and driver that support OpenGL 3.2 or later.
  • If you are on Windows and upgrading from version 1.0.31 (three versions ago):
    • The Windows installer now defaults to an installation for all users of the machine. This exposes a bug in the Windows Installer system that stops the upgrade from version 1.0.31-beta from working correctly. As such, you must manually uninstall version 1.0.31-beta using the “Programs and Features” control panel before installing 1.8.0-beta.
    • To install 1.8.0-beta only for the current user, select the “Advanced” option after accepting the EULA in the Window installer.

Downloads

Release Notes for 1.8.0-beta

Creation Platform Changes

API Refactoring

Based on feedback from users this release involves a thorough review and update of the Creation Platform API. There were several overall goals to the refactoring of the API.

  • Reduce the use of keyword arguments. Throughout the CreationPlatform API, there was prolific use of keyword arguments to constructors, which didn’t represent good coding style.
  • Reduce the number of arguments passed to constructors. Often constructors were taking large numbers of arguments, mainly because the number of arguments was obscured by the use of keyword arguments.
  • Reduce the use or generated functions. A lot of the functions exposed on the interfaces to nodes were generated using string concatenation. This technique results in interfaces where the source of functions could be confusing for new users.
  • Make the code more readable and therefore easy to learn. We have reduced the use of Python specific code in favor of more explicit language neutral code. The code has become more verbose, by eliminating confusing convenience functions that tended to increase the learning curve for new users.

Explicit Constructor Arguments

The scene graph node constructors in the past took only keyword arguments, which lead to confusion when reading the API. In the older API, constructor arguments were not explicitly defined, and all arguments were passed in as a keyword arguments dictionary.

  • Arbitrary values could be passed into any constructor, as the constructors signature did not specify any specific arguments, or their default values if none were passed.
  • Code completion tools failed to generate hints for these constructors as the arguments were not defined.
  • Default values were assigned to arguments stored in the options dictionary, rather than being declared in constructor.
  • Often the possible values passed to a constructor were defined deep in the constructor definition, making the code difficult to learn.

The following code shows the Time node’s constructor arguments. As you can see, the previous constructor took only keyword arguments and all default values are assigned in the body of the constructor.

– Old Constructor definitions.

class Time(BaseTime):
  """The time node provides functionality for modifying the time, such as playback for example."""

  def __init__(self, scene, **options):
    # process the default options
    options.setdefault('fps', 48.0)
    options.setdefault('fixedStep', True)
    options.setdefault('playFromStart', False)
    options.setdefault('startTime', 0.0)

    options.setdefault('viewport', None)
    options.setdefault('attachViewports', True)
    options.setdefault('uiMin', 0.0)
    options.setdefault('uiMax', 100.0)
    options.setdefault('timeAsSeconds', True)
    options.setdefault('timeRange', Vec2(0.0,10.0))
    options.setdefault('snapFrame', True)

    # call the baseclass constructor
    super(Time, self).__init__(scene, **options)

– New Constructor definitions

Now all constructors take explicit arguments that are defined in the constructor signature. The Time node now takes the same set of arguments, but they are explicitly declared in the constructor signature along with the default values.

class Time(BaseTime):
  """The time node provides functionality for modifying the time, such as playback for example."""

  def __init__(self, scene,
      fps = 48.0,
      fixedStep = True,
      playFromStart = False,
      startTime = 0.0,

      timeAsSeconds = True,
      timeRange = Vec2(0.0,10.0),
      snapFrame = True,

      viewport = None,
      attachViewports = True,

      playMode = 0,

      **kwargs):

    # call the baseclass constructor
    super(Time, self).__init__(scene, **kwargs)

Note: most node constructors still take an optional kwargs argument that enables propagation of arguments up through the inheritance hierarchy. Developers may of course wish to implement nodes that do not take keyword arguments, but we have left this functionality for the sake of backwards compatibility.

Generally, calling code that constructs nodes will not need to be modified. In some cases, because the arguments to the constructors must be defined somewhere in the class hierarchy of the node, invalid arguments will now generate errors, where in the past they were simply ignored.

Ports

The use of the name ‘ReferenceInteface’ has been replaced with the more explicit ‘InPort’, which refers to Port the data structure used to manage connections between nodes in the graph.

In previous implementations of the scene graph, references were added to a node to create connections between nodes. When a reference interface was added to the node, several functions were generated and assigned to the nodes instance to facilitate creating, removing, retrieving of the connected nodes. This has now been replaced with a more explicit syntax where the port is retrieved, and the connections queried directly.

# This method generates a collection of functions on the interface of 'self' for  creating connections in the graph.
self.addReferenceInterface('InputTime', BaseTime, False, self._changeTimeNode)

# e.g. we can create a connection in the graph using 'set' + ReferenceName + 'Node'.
self.setInputTimeNode(options['time'])

# we can access a connection in the graph using 'get' + ReferenceName + 'Node'.
node = self.getInputTimeNode()

The new code style prefers explicit port access, and the generated functions now emit deprecation warnings when used.

self.addInPort('InputTime', BaseTime, self._changeTimeNode)

# retrieve the added port by name, and set the connection explicitly
self.getInPort('InputTime').setConnectedNode(time)

The function ‘addReferenceInterface’ now generates a warning when used, recommending the use of the new method ‘addInPort’. e.g.

“WARNING: addReferenceInterface is deprecated. Use addInPort instead. Called from: TimeImpl.py:56”

Note: The function signature for addInPort varies slightly from that of ‘addReferenceInterface’

def addReferenceInterface(self, name, cls, isList = False, changeCallback = None, visibleInUI = True, callbackData = None):
  ...

VS

def addInPort(self, name, cls, callback, supportsMultipleConnections = False):
  ...

‘addInPort’ takes the name, class and callback values first, while ‘supportsMultipleConnections’ is an optional last argument.

  • ‘changeCallback’ was renamed to ‘callback’
  • ‘isList’ was renamed to ‘supportsMultipleConnections’
  • ‘visibleInUI’ and ‘callbackData’ were both deprecated as neither were being used. The use of ‘callbackData’ can be eliminated when the callback function is defined as a closure function with access to data in the parent scope.

Parameters

The use of the term ‘ValueInterface’ has been replaced with ‘Parameter’, and an explicit class has been introduced to represent a Parameter. In the past, the values and functions that made up a value interface were stored in a dictionary and therefore were not well encapsulated. Meta data about the value interface was simply added to the dictionary along with everything else, and there was no clear owner of the data. The new Parameter class owns the functions used to get/set the value and the associated meta data.

Value interfaces were added to a node to expose data. The value interface is used to generate user interfaces, and provide a methods for retrieving or modifying data stored in a node or one of its dependency graph nodes. When a value interface was added to a node instance, it would add generated functions to the instance for getting and setting the value. These generated functions could be confusing to new developers as the definition of the functions could not be located by searching.

self._addValueInterface('myValue', 'Scalar', getMyValue, setMyValue)

# use the generated function to retrieve the value.
# the generated function follows the convention of 'get' + (M)yValue
myValue = self.getMyValue()

Now Parameters are used to expose data on the interface of the node, and although the generated functions are still assigned to the node instance, these functions are now deprecated, and in future versions will no longer be generated.

self.addParameter('myValue', 'Scalar', getMyValue, setMyValue)

# retrieve the parameter and get its value.
myValue = self.getParameter('myValue').getValue()

Parameter Groups

ValueInterface groups have been replaced with ParameterGroups’, and a new class has been defined that encapsulates the concept of a group of parameters.

# start a new value interface group
self._beginValueInterfaceGroup('instances', getCountCallback=dgnode.getCount, setCountCallback=dgnode.setCount, displayElementCallback=isSelected )

Parameter groups enable a collection of parameters that share a slice count to be exposed on a node, and be used to generate user interfaces that reflect the shared slice count. Added parameters groups can be queried by name and modified.

# start a new parameter group
self.beginParameterGroup('instances', getCountCallback=dgnode.getCount, setCountCallback=dgnode.setCount, displayElementCallback=isSelected )

The use of valueInterfaces is still supported, but the generated functions report deprecation warnings. Code can be migrated to follow the new convention by following the instructions included in the deprecation warnings. The base class ‘ValueInterfaces’ that both SceneGraphNode and Component were derived from has been renamed to ‘ParametersInterface’.

Components

Component classes now have explicit constructor arguments as nodes do.

_setDefaultOptions, _hasOption, _getOption, and _getOptions have now been deprecated. Component classes now handle caching of constructor arguments between the construction and apply of the component.

registerComponentClass no longer takes the name of the class as a parameter. The class name is readily available on the class. A deprecation warning is now generated when a name argument is passed to registerComponentClass.

Widgets

The refactoring of Value interfaces caused a cascading refactoring of the widget classes which resulted in a cleanup of the Widget system.

  • The ‘Widgets/RT’ folder was renamed to ‘Widgets/Parameters’ to reflect the more broad application of widgets than for displaying registered types.
  • All Parameter widgets are now derived from a base class called ‘ParameterWidget’, which is derived from QtGui.QWidget. This eliminated a lot of multiple inheritance in the widget classes.
  • All widget constructors now take a fixed set of explicit arguments: parameter, index, addEventListener, and parentWidget.
  • Meta data for the widgets is now stored in a dictionary in the Parameter class, and the widgets directly retrieve these values using parameter.getOption/parameter.setOption
  • The static method ‘canDisplay’ was modified to take a single Parameter class and return true or false.
  • registerRTWidget was deprecated in favor of ‘registerParameterWidget’. registerParameterWidget takes no arguments, and should be called using the derived class.

Application Services

The base application classes were also refactored to make the constructor arguments explicit, and to reduce the number of arguments passed when constructing the application. In the past, the ‘CreationPlatformApplication’ class constructor took a large number of arguments and set up all services within the constructor function. Many additional using optional arguments such as ‘setupCamera’ or ‘setupSelection’ were required to specify which services were setup, along with configuration options for these services. The number of potential arguments to the constructor was too large, and so for this release, the constructor was broken into smaller functions which can be explicitly called to setup the services. These functions now enable a finer grained configuration of the application services, while reducing the number of arguments to the constructor.

  • setupViewports is an explicit function that must be called to setup the viewports.
  • setupCamera is an explicit function that must be called to setup the camera. The numerous arguments to camera configuration are now all exposed on this function. The base class does not automatically setup a camera for the developer, requiring the user to explicitly call setupCamera if they wish the base class to setup the default camera.
  • setupGrid is an explicit function that must be called to setup the grid.
  • setupGlobalTimeNode is an explicit function that must be called to setup the time node, and the time control widget.
  • setupSelection is an explicit function that must be called to setup the selection manager.
  • setupPersistence is an explicit function that must be called to setup the file save/load menus and persistence framework.

Existing applications will required to be manually updated to support the revised implementation of ‘CreationPlatformApplication’. The many sample applications that come in the demos download package should serve as a good example to follow when updating your applications.

Documentation

Full API documentation

We are now using Sphinx api-doc to autogenerate a complete reference manual for Creation Platform. All classes, their constructors and public functions are now documented in the Creation Platform Reference, with doc strings in most cases. We have migrated some of our previous documentation to doc strings in the Python source code. API documentation is a continuous area of work, and we will continue to add details to the doc strings based on feedback.

Realtime renderer

  • New ShaderLibrary and MaterialLibrary nodes allow for simplified scene graphs and faster load times by regrouping various materials and shaders under a single node. Note: the MaterialLibrary node is currently only used for render passes’ materials, since it doesn’t expose parameters in the UI (no interactive changes).
  • Realtime soft shadows are now supported for all light types (percentage closer soft shadows). Soft shadows will be enabled by using the new types AreaDirectionalLight, AreaPointLight and AreaSpotLight, combined with the basicRenderPasses = False application constructor parameter.
  • Support for shader preprocessor parameters, which will trigger dynamic compilation of shaders based for each set of preprocessor values (used by soft shadow shaders).
  • Support for texture arrays as render target and input textures (used by cascaded soft shadow shader).

Creation Core Changes

  • report() statements are now immediately output when report() is called rather than being buffered.
  • Added environment variable FABRIC_ENABLE_CRASH_HANDLER to dump debug information when a crash occurs.
  • Fixes for several minor crashes in KL code and cache.
  • Clarified KL error messages.
  • Added inline documentation to CreationCore.h header file.

Installing Creation Platform

Creation Platform runs on Windows 7 SP1 (both 32- and 64-bit), CentOS 6.3, Ubuntu 10.04 LTS, Ubuntu 12.04 LTS, and Mac OS X 10.7 “Lion” or later.

Install Python

If you don’t already have Python on your system, you need to install it first.

  • For Windows, you can get the latest version of Python 2.7 directly from http://python.org. You will also need to add the Python folders, usually C:\Python27, and C:\Python27\Scripts, to your PATH environment variable.
    • On 64-bit Windows, we also provide a build of Creation Platform that works with Python 2.6.
  • For CentOS 6.3, Ubuntu 10.04 LTS and Ubuntu 12.04 LTS, your system already came with the right version of Python installed.
  • For OS X, Python 2.7 is automatically installed on your system as part of the base OS install.
    • IMPORTANT NOTE: On Mac OSX you must use the system-installed version of Python found in /usr/bin/python. Using a different version of Python (installed via MacPorts or HomeBrew for example) will result on a crash when trying to run any Creation Platform application.

Once the install is finished, make sure that you are able to open a command prompt and run python. Windows users will probably have to add the directory in which Python was installed (usually c:\Python27) to their PATH environment variable.

Upgrading from 1.0.30-beta: Uninstall Old Version of Creation Platform, Creation Core and PySide

In Creation Platform 1.0.31-beta, we switched to using a single installer for Creation Platform (rather than two separate installers as in previous releases). This single installer also installs the PySide framework.

If you are still running Creation Platform 1.0.30-beta or earlier, you will need to manually uninstall this version, including the Creation Core, as well as any previously-installed versions of PySide. The instructions for doing so vary by platform:

  • Windows: use the “Programs and Features” control panel to first remove “Fabric Engine Creation Platform”, then remove “Fabric Engine Core”, then remove “Python 2.7 PySide-.....” (where .... is the version information). You will need to do this as a user with administrator privileges.
  • Linux (Ubuntu/Debian): use the command line (“dpkg -r”) or a GUI tool (eg. Ubuntu Software Center) to first remove the “fabricengine-creation-platform” package, then the “fabricengine-core” package. You should then run “apt-get remove python-pyside” and then “apt-get autoremove” to remove the existing PySide from your system. You will need to do all of these as an administrator (eg. using the sudo command).
  • Mac OS X: Manually delete the /Library/FabricEngine folder and all of its subfolders (ie. using the Finder or using the command “rm -rf /Library/FabricEngine” from the terminal). You must then also remove PySide from your system. If you installed PySide using MacPorts, run “sudo port uninstall py27-pyside @1.1.0_1+universal” (the version number may be different for you; you can see it by running “port list py27-pyside”). If you installed PySide from Nokia’s website, run the uninstaller provided by Nokia. You will need to do both of these as an administrator (eg. using the sudo command).

NOTE: On Windows, you may continue to use the official build of PySide, leaving it installed; however, we have experienced stability issues with the official build that are fixed in the version that is installed with Creation Platform. If you still want to use the official PySide build, use the “Advanced” option in the Creation Platform installer to deselect the PySide module before proceeding with installation. Install Creation Platform

From the Downloads section, download and install Creation Platform for your platform.

  • On Windows 7 32-bit, the installer is CreationPlatform-1.8.0-beta-Windows-32Bit-Python2.7.msi. It is a .MSI file that can be run directly. Note that the installer is unsigned, so your browser may tell you it’s not safe to run it.
  • On Windows 7 64-bit, the installer is CreationPlatform-1.8.0-beta-Windows-64Bit-Python2.7.msi (for Python 2.7) or CreationPlatform-1.7.3-beta-Windows-64Bit-Python2.6.msi (for Python 2.6). It is a .MSI file that can be run directly. Note that the installer is unsigned, so your browser may tell you it’s not safe to run it.
  • On CentOS 6.3, the installer is CreationPlatform-1.8.0-beta-CentOS-x86_64-Python2.6.rpm. It is a .rpm package that can be installed using ‘rpm -i’ or using a GUI tool.
    • IMPORTANT NOTE: you must log out and log back in in order to get the environment variables set that Creation Platform needs to run!
  • On Ubuntu 10.04 LTS, the installer is CreationPlatform-1.8.0-beta-Ubuntu-amd64-Python2.6.deb. It is a .deb package that can be installed using ‘dpkg -i’ or using a GUI tool.
    • IMPORTANT NOTE: you must log out and log back in in order to get the environment variables set that Creation Platform needs to run!
  • On Ubuntu 12.04 LTS, the installer is CreationPlatform-1.8.0-beta-Ubuntu-amd64-Python2.7.deb. It is a .deb package that can be installed using ‘dpkg -i’ or using a GUI tool.
    • IMPORTANT NOTE: you must log out and log back in in order to get the environment variables set that Creation Platform needs to run!
  • On Mac OS X Lion or Mountain Lion, the installer is CreationPlatform-1.8.0-beta-MacOSX-64Bit.dmg. It is an executable on a .dmg file that can be run directly from the mounted disk image.
    • IMPORTANT NOTE: you must restart your system in order to get the environment variables set that Creation Platform needs to run!

Test Creation Platform

The Creation Platform installer ships with a simple application, HelloCreation, that can be used to test the installation. To run HelloCreation:

  • On Windows:
  • Open a command prompt (cmd.exe)
  • Change to the Creation Platform install directory (usually C:\Program Files\Creation Platform for per-machine installs and C:\Users\<USERNAME>\AppData\Local\Apps\Creation Platform for per-user installs)
  • Run python UtilsHelloCreation.pyw
  • On Ubuntu, open a shell and run python /usr/lib/creation-platform/Python/HelloCreation.pyw
  • On CentOS, open a shell and run python /usr/lib64/creation-platform/Python/HelloCreation.pyw
  • On Mac OS X, open Terminal and run hello-creation

Install Sample Applications (“Demos”)

From the Downloads section, download the CreationPlatform-1.8.0-beta-Demos.zip file, which you can extract to a location of your choosing. The demos are located below the Apps subfolder of the created CreationPlatform-Demos-1.8.0-beta folder, and are identical for all platforms. These demos can be run using the python command; for example, python Apps/GeometryDeformation.py.

Documentation

Complete documentation for Creation Platform can be found in Fabric Engine Unofficial Documentation 日本語版.

After installing Creation Platform, you can also find the documentation in the Start menu in Windows, the Applications menu in CentOS and Ubuntu, and through a link in the ‘/Applications/Creation Platform’ folder in Mac OS X. The documentation can be accessed from the “Help” menu of Creation Platform applications.

Optional: Compiling the DCC Integrations

In order to use the DCC integrations after you have installed Creation Platform you will need to download the CPCAPI (Creation Platform C++ API) source files here: CPCAPI for Creation Platform 1.8.0-beta

You will then need to consult the .. kl-extlist:: DCCIG, in particular the section on “Installing and using the CPCAPI”. In there you will find instructions on how to compile and any necessary environment variables that must be set.

The currently supported DCC integrations are:

  • Maya 2013 on Windows 64-bit
  • Maya 2013 on Linux 64-bit
  • SoftImage 2013 on Windows 64-bit

That’s it!

Indices and Tables