Circle Image

Pixaflux

Sprite It - C++ SDK

The Sprite It C++ SDK is a small library that tries to mimic the Lua Sprite It SDK as close as possible. It tries to avoid the use of pointers and heap memory in Sprite It programs, and leaves all memory management to the calling application.

Converting a Sprite It Lua program to a C++ program is mostly a matter of changing the format of one text file.

Building Sprite It

The Sprite It SDK is located in a zip file in the PixaFlux installation directory.

C:\Program Files\PixaFlux\SpriteIt\Cpp\SpriteIt.zip

Required Tools

Extracting

Locate the zip file and extract it to an empty directory:

D:\Projects\SpriteIt

After extracting the zip, you'll see a new code subdirectory with the SpriteIt SDK files:

D:\Projects\SpriteIt\code

Generating the Visual Studio Solution

The Visual Studio project is generated by CMake. Open CMake and set the code and build directories:

Code:

D:\Projects\SpriteIt\code

Build:

D:/Projects/SpriteIt/vs2017_64b

Click Configure and set the generator to Visual Studio 15 2017 and the platform to x64.

Configure

Click Generate.

Generate

This generates the Visual Studio 2017 solution that builds Sprite It.

Options

BUILD_TESTS. If checked, builds the test projects. These projects show how build Sprite It DLLs, and have samples of all nodes and functions.

Building Sprite It

Open Visual Studio 2017, and open the SpriteIt.sln file generated by CMake

D:\Projects\SpriteIt\vs2017_64b\SpriteIt.sln

Visual Studio Solution

Build it

Build > Build Solution

Configurations

Debug This configuration is useful for debugging a project using the AppTest executable, but DLL files built in Debug mode won't run in PixaFlux, which is distributed in Release mode.

Release This is the configuration required to run Sprite It in PixaFlux.

Adding new projects

The easiest way to add a new project is to clone the directory of an existing project and rename it. There are two types of projects: Value output (Dust.dll, Fragments.dll, etc) and Material output (Concrete.dll, Rust.dll).

After copying the project, modify the CMakeLists.txt file to add the new project SET name and ADD_SUBDIRECTORY command:

SET( SPOTS "Spots" )
SET( NEW_PROJECT "NewProject" )

...

ADD_SUBDIRECTORY( ${SPOTS} )
ADD_SUBDIRECTORY( ${NEW_PROJECT} )

Rename the cpp and def files in the project directory:

Visual Studio Solution

Rename the module in the def file:

LIBRARY   NEW_PROJECT
EXPORTS
   GetAttributes   @1
   ResolveAttributes   @2
   GetSpriteContext   @3

And replace the CMake variables in the CMakeLists.txt file.

SET ( SOURCE_FILES  "${NEW_PROJECT}.cpp" "${NEW_PROJECT}.def" )

SET ( PUBLIC_INCLUDE_DIRS "${CMAKE_SOURCE_DIR}" )

SOURCE_GROUP( "Files" FILES ${HEADER_FILES} ${SOURCE_FILES} )

INCLUDE_DIRECTORIES ( ${PUBLIC_INCLUDE_DIRS} )
ADD_LIBRARY ( ${NEW_PROJECT} SHARED ${SOURCE_FILES} ${HEADER_FILES} )
TARGET_LINK_LIBRARIES( ${NEW_PROJECT} ${SPRITE_IT} )

SET_TARGET_PROPERTIES( ${NEW_PROJECT} PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_LIBRARY_OUTPUT_DIRECTORY} )
SET_TARGET_PROPERTIES( ${NEW_PROJECT} PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY} )
SET_TARGET_PROPERTIES( ${NEW_PROJECT} PROPERTIES OUTPUT_NAME ${NEW_PROJECT} )

ADD_CUSTOM_COMMAND(TARGET ${NEW_PROJECT} POST_BUILD
                   COMMAND ${CMAKE_COMMAND} -E copy 
                   $<TARGET_FILE:${NEW_PROJECT}> 
                   "${CMAKE_SOURCE_DIR}/../../Bin/$<CONFIGURATION>/$<TARGET_FILE_NAME:${NEW_PROJECT}>"
)

Now the code is ready to be regenerated with CMake. The Visual Studio solution will include the NewProject.

Notable Differences

Random seed and image size and position

In Lua the random seed and image size and position can be queried using a set of functions defined by the SpriteIt node. In the C++ SDK, these values can be accessed from the attributes instance in the ResolveAttributes call:

attributes.GetSeed()
attributes.GetSizeX()
attributes.GetSizeY()
attributes.GetPositionX()
attributes.GetPositionY()

List indices

A key difference between C++ and Lua is that array indices in C++ start at 0, and in Lua they start in 1.

To match c++ functionality, the iteration variable also starts in 0 in the tiles, branch and iterator nodes.

Levels

In Lua and c++ the state level member starts at 1 and is incremented by branch nodes. When using the level variable as an index in a list in c++ it must be subtracted by 1.

See 18.BranchLists.lua

offset = {0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8}

function BranchOffset(spriteContext, state)
    local o = spread * offset[state.level]
    local v = vector2(o, o)
    return v
end

Test18BranchLists.cpp

std::array<float, 8> offset = { 0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f };

Vector2 BranchOffset(const Context &context, const State &state)
{
    float o = spread * offset[state.mLevel - 1];
    Vector2 v(o, o);
    return v;
}

Random

In Lua, the random functions are defined in the math library:

math.random()

In c++, the random functions are provided by the default random engine standard library

std::default_random_engine mEngine;

And it's managed by the Random class:

Returns a random float number between 0.0 and 1.0.

static float Get()

Returns a random integer between min and max, both included.

static int Get(int min, int max)

Returns a random float between min and max, both included.

static float Get(float min, float max)