Display Driver Plug-ins

group DD

Functions

bool Bootstrap(const std::string &katanaPath)

The Display Driver Host API allows to initialize the host.

Bootstraps the API without having to link against the internal libraries that implement the Display Driver host. This can be useful when implementing an executable that needs to use the Display Driver API via the plug-in system, without having to link against any internal library.

Returns true if the bootstrap succeeds.

void Initialize(const FnDisplayDriverHostSuite_v1 *)

Initializes the API with the given Display Driver Host suite.

void encodeLegacyName(const std::string &legacyFrameName, int legacyFrameNumber, std::string &buffer)

This is a utility function to allow the simple encoding of legacy frameNames and frame numbers to be used with the latest Render Data Protocol.

Parameters
  • legacyFrameName -

    the frame name to be encoded.

  • legacyFrameNumber -

    the frame number to be encoded.

  • buffer -

    where the encoding can be found.

class CloseMessage
#include <CloseMessage.h>

The CloseMessage class encapsulates the message sent to Katana instructing it that there is no more data for the specified channel.

The CloseMessage message should only be sent down the pipe when no more data is to be sent for the channel.

It is un-likely you will ever need to directly instantiate this class as it is handled for you in the closeChannel method of the KatanaPipe.

See
KatanaPipe.

Inherits from Foundry::Katana::Message

Public Functions

CloseMessage(const NewChannelMessage &channel)

Create a new instance of a CloseMessage message that, when sent to Katana will let the Catalog Server know that there is no more data to be sent through for this specified channel.

Parameters
  • channel -

    the channel object that will be closed

CloseMessage(const uint8_t *frameID, uint16_t channelID = 0)

Create a new instance of a CloseMessage message that, when sent to Katana will let the Catalog Server know that there is no more data to be sent through for this specified channel.

Parameters
  • frameID -

    a pointer to a 16 byte array containing a unique frameID

  • channelID -

    the channel ID for the channel that should be closed.

virtual ~CloseMessage()
class DataMessage
#include <DataMessage.h>

The DataMessage class encapsulates the message sent to the Katana Catalog Server (KCS) which actually contains image data for a given channel.

The DataMessage message should be sent down the KatanaPipe after a NewFrame & NewChannel messages have been sent.

A DataMessage represents a region of pixel data within a particular channel. The region may be as small as 1 pixel or as large as the whole channel. i.e. you can send the entire channel’s data in on DataMessage.

Any chunks of data passed to the DataMessage will be copied by the instance and sent asynchronously on an I/O thread.

Inherits from Foundry::Katana::Message

Public Functions

DataMessage(const NewChannelMessage &channel, uint32_t xMin = 0, uint32_t width = 0, uint32_t yMin = 0, uint32_t height = 0, uint32_t byteSkip = 0)

Create a new instance of a DataMessage message using an existing NewChannel object to obtain the unique frame ID and channel ID.

The default constructor will create a DataMessage belonging to the specified channel with all values set to 0 and an empty data buffer.

See
setData()
Parameters
  • channel -

    an existing NewChannel object

  • xMin -

    the starting x coordinate in the channel relative to the channel’s origin

  • width -

    the number of pixels wide this data extends for.

  • yMin -

    the starting y coordinate in the channel relative to the channel’s origin.

  • height -

    the number of pixels high this data extends for.

  • byteSkip -

    number of bytes to skip over to get to next pixel data (this is also stored in the channel data but, added here if the data packets differ for any reason).

DataMessage(const uint8_t *frameID, uint16_t channelID = 0, uint32_t xMin = 0, uint32_t width = 0, uint32_t yMin = 0, uint32_t height = 0, uint32_t byteSkip = 0)

Create a new instance of a DataMessage message using a pointer to a 16 byte array containing a unique frame ID.

The default constructor will create a DataMessage belonging to the specified channel with all values set to 0 and an empty data buffer.

See
setData()
Parameters
  • frameID -

    a pointer to a 16 byte array containing a unique frameID

  • channelID -

    the channel ID for the channel this data belongs to.

  • xMin -

    the starting x coordinate in the channel relative to the channel’s origin

  • width -

    the number of pixels wide this data extends for.

  • yMin -

    the starting y coordinate in the channel relative to the channel’s origin.

  • height -

    the number of pixels high this data extends for.

  • byteSkip -

    number of bytes to skip over to get to next pixel data (this is also stored in the channel data but, added here if the data packets differ for any reason).

virtual ~DataMessage()

Destroy the DataMessage instance and free any resources it holds.

void setData(const void *data, uint32_t size, FnPixelDataDeleter pixelDataDeleter = NULL)

Set the data payload for this DataMessage.

Sets the data payload for this message to the buffer pointed to by data by copying it into an internal buffer.

Data pointed to by data will remain under the control of the caller unless the user provides an FnPixelDataDeleter. In which case, the DataMessage will take ownership of the buffer and call the free function when the buffer is no longer required. If using an FnPixelDataDeleter it is not safe to access the data buffer once KatanaPipe::send() has been called.

Note: 4-channel color data is expected to be encoded as ARGB unless modified by the NewChannelMessage.

See
NewChannelMessage and NewChannelMessage_v2
Parameters
  • data -

    - pointer to the array data

  • size -

    - size of the data to be sent.

  • pixelDataDeleter -

    - function that if specified .

void setStartCoordinates(uint32_t x, uint32_t y)
void setDataDimensions(uint32_t width, uint32_t height)
void setByteSkip(uint32_t byteSkip)
const uint8_t *frameUUID() const

Get the unique 128 bit identifier that is assigned to the frame this data message is a member of.

Return
a pointer to the start of the 16 byte array that contains the unique frame ID.

uint16_t channelID() const
uint32_t xMin() const
uint32_t width() const
uint32_t yMin() const
uint32_t height() const
uint32_t bufferSize() const
const void *dataBuffer() const

Returns the data buffer that will be sent when KatanaPipe::send() is called.

Note
If setData() was called with an FnPixelDataDeleter function this method will return NULL after a call to KatanaPipe::send().

uint32_t byteSkip() const
class EndOfRenderMessage
#include <EndOfRenderMessage.h>

The EndOfRenderMessage class encapsulates the message sent to Katana instructing it that there is no more data for the specified channel and it can clear up any data structures that it maintains for this channel.

The EndOfRender message should only be sent down the pipe when no more data is to be sent for the channel.

See
KatanaPipe.

Inherits from Foundry::Katana::Message

Public Functions

EndOfRenderMessage(const NewChannelMessage &channel)

Create a new instance of a EndOfRenderMessage message that, when sent to Katana will let the Catalog Server know that there is no more data to be sent through for this specified channel.

Parameters
  • channel -

    the channel object that will be closed

EndOfRenderMessage(const uint8_t *frameID, uint16_t channelID = 0)

Create a new instance of a EndOfRenderMessage message that, when sent to Katana will let the Catalog Server know that there is no more data to be sent through for this specified channel.

Parameters
  • frameID -

    a pointer to a 16 byte array containing a unique frameID

  • channelID -

    the channel ID for the channel that should be closed.

virtual ~EndOfRenderMessage()
class KatanaPipe
#include <KatanaPipe.h>

The KatanaPipe is used to send messages to the specified Katana Catalog Server.

It is a uni-directional communication pipe that allows a message to be sent to the end-point specified in the constructor. The end-point will usually be Katana however any process implementing the Render Data Protocol could serve as the end-point.

Very important The pipe is not thread safe. If you require communication capabilities from more than a single thread you should create an instance of the KatanaPipe for each thread however you should find this is not necessary.

Public Functions

KatanaPipe(const std::string &hostName, unsigned int portNumber, const size_t maxQueueSize)

Create a new instance of the KatanaPipe which will be connected to the specified host name and port number.

The constructor will not attempt to create the actual connection to the specified host name and port number. To do this you must call connect()

See
connect()
Parameters
  • hostName -

    a host name that specifies the end point to be connected to. This must be network visible from the host you are connecting from.

  • portNumber -

    the TCP port which the end-point on the specified hostName is listening for messages on.

  • maxQueueSize -

    the maximum number of messages we can store in the outgoing thread safe queue and control queue.

~KatanaPipe()

Destroy this Katana Pipe.

This will close the connection to the end-point, any unsent messages in the buffer will be sent.

int connect()

Initiate the connection to the end-point specified by the host name and port number provided at construction.

connect() must be called before any messages are sent. Calling connect() after the pipe has been connected will not have any effect.

Return
0 if the pipe connects successfully to the end-point otherwise nonzero.

int send(const Message &message)

Send a message to the end-point this pipe is connected to.

send() pushes a message down the pipe to the end-point this pipe is connected to. send() ensures the message is either sent in its entirety or not at all.

Return
0 if the message is sent successfully - otherwise nonzero.
Parameters
  • message -

    the message to be send.

void flushPipe(const NewChannelMessage &channel)

This is an important synchronisation function that you should called when your renderer has sent all image data to the driver for a given channel.

It will block until all data has been cleared from this end of the pipe.

void closeChannel(const NewChannelMessage &channel)

This is an important function that you should call from your driver when there is no more data to be sent for this channel, ever.

Once this message has been sent Katana will ignore any further image data.

Public Static Functions

static FnPlugStatus setHost(FnPluginHost *host)

Set the Display Driver Host to delegate all communication details to the suite.

The KatanaPipeSingleton bootstraps and sets the host suite, and is recommended to initialize a communication pipe.

static void setSuite(const FnDisplayDriverHostSuite_v1 *suite)
static const FnDisplayDriverHostSuite_v1 *getSuite()

Get the Display Driver host suite for communication pipes. If invalid, an error message is output to the standard error stream.

Return
the Display Driver host suite.

class PipeSingleton
#include <KatanaPipeSingleton.h>

The PipeSingleton provides a singleton wrapper around the KatanaPipe.

See
KatanaPipe

Public Static Functions

static KatanaPipe *Instance(const std::string &hostName, unsigned int portNumber, const std::string &katanaPath = std::string())

Return the KatanaPipe connected to the given hostName and portNumber

Currently, we only support the connection back to one KCD i.e. the first call to this function will define the hostName/portnumber combination that will be connected to. Subsequent calls to this function with different hostname portnumber combinations will continue to return the original pipe.

Return
the KatanaPipe connected to the specified end point.
Parameters
  • hostName -

    the hostName to be connected to as a fully qualified domain name.

  • portNumber -

    the TCP port number to the Catalog Server is listening on.

  • katanaPath -

    the path where Katana was installed to bootstrap the Display Driver host library. By default it looks for the KATANA_ROOT environment variable set by a Katana interactive or render session.

static size_t GetQueueSize()

Returns the maximum number of messages that will be queued before calls to KatanaPipe::send() will begin to block. The environment variable KATANA_PIPE_MAX_QUEUE_SIZE, if set to a non-zero positive value can be used to configure this setting.

Return
the maximum number of messages that will be queued before calls to KatanaPipe::send() will begin to block.

class Message
#include <Message.h>

This is the base class against which all Messages sent to Katana should inherit from.

Subclassed by Foundry::Katana::CloseMessage, Foundry::Katana::DataMessage, Foundry::Katana::EndOfRenderMessage, Foundry::Katana::NewChannelMessage, Foundry::Katana::NewFrameMessage

Public Functions

Message()
Message(FnMessageHandle handle)
virtual ~Message()
bool isValid() const

Check if the message has a valid handle to the host suite.

Return
true if the message handle can be used to get/set data and send through the communication pipe.

Public Static Functions

static FnPlugStatus setHost(FnPluginHost *host)

Set the Display Driver Host to delegate message initialization and protocol details to the suite.

The KatanaPipeSingleton bootstraps and sets the host suite, and is recommended to initialize the message suite.

static void setSuite(const FnDisplayDriverHostSuite_v1 *suite)
static const FnDisplayDriverHostSuite_v1 *getSuite()

Get the Display Driver host suite for messages. If invalid, an error message is output to the standard error stream.

Return
the Display Driver host suite.

class NewChannelMessage
#include <NewChannelMessage.h>

The NewChannelMessage class encapsulates the message sent to the Katana Catalog Server (KCS) to specify that a new channel should be reserved in the Catalog for a given frame.

The NewChannelMessage message should be sent down the KatanaPipe after a NewFrame message has been sent as the NewFrame message will reserve the frame in the Catalog.

A channel represents a given output pass by a renderer, such as the primary colour pass, id pass, depth pass P pass etc.

Each NewChannelMessage object must be created with with reference to a valid unique frame ID so Katana will know which frame the channel belongs to.

Inherits from Foundry::Katana::Message

Subclassed by Foundry::Katana::NewChannelMessage_v2

Public Functions

NewChannelMessage(const NewFrameMessage &frame, uint16_t channelID = 0, uint32_t height = 0, uint32_t width = 0, int xorigin = 0, int yorigin = 0, float sampleRate1 = 0.0, float sampleRate2 = 0.0, uint32_t dataSize = 0)

Create a new instance of NewChannelMessage message using an existing NewFrame object to obtain the unique frame ID.

The default constructor will create a new channel belonging to the specified frame with all values set to 0 and an empty string for the channel name.

Note: the NewChannelMessage object will NOT maintain a reference to NewFrameMessage or assume ownership of it.

See
setChannelName()
Parameters
  • frame -

    an existing NewFrameMessage object

  • channelID -

    an ID number to identify this channel within the frame. (This can just be sequential from zero).

  • height -

    the height of this channel in pixels.

  • width -

    the width of this channel in pixels.

  • xorigin -

    the x origin of this channel relative to the frame’s x origin

  • yorigin -

    the y origin of this channel relative to the frame’s y origin.

  • sampleRate1 -

    sampleRate1

  • sampleRate2 -

    sampleRate2

  • dataSize -

    the size - in bytes - of a single pixel of data for this channel.

NewChannelMessage(const uint8_t *frameID, uint16_t channelID = 0, uint32_t height = 0, uint32_t width = 0, int xorigin = 0, int yorigin = 0, float sampleRate1 = 0.0, float sampleRate2 = 0.0, uint32_t dataSize = 0)

Create a new instance of a NewChannelMessage specifying a pointer to a 16 byte array that will contain a unique frame ID.

The default for other values will create a new channel belonging to the specified frame with all values set to 0 and an empty string for the channel name.

See
setChannelName()
Parameters
  • frameID -

    a pointer to a 16 byte array containing a unique 128 bit frame ID.

  • channelID -

    an ID number to identify this channel within the frame. (This can just be sequential from zero).

  • height -

    the height of this channel in pixels.

  • width -

    the width of this channel in pixels.

  • xorigin -

    the x origin of this channel relative to the frame’s x origin

  • yorigin -

    the y origin of this channel relative to the frame’s y origin.

  • sampleRate1 -

    sampleRate1

  • sampleRate2 -

    sampleRate2

  • dataSize -

    the size - in bytes - of a single pixel of data for this channel.

virtual ~NewChannelMessage()

Destroy the NewChannelMessage instance.

int setChannelName(const std::string &name)

Set the human readable name that will be seen in the Monitor.

The maximum number of characters that can be specified in name is 8000.

Return
0 if the name was set successfully, otherwise nonzero, if nonzero is returned the existing name will remain unchanged.
Parameters
  • name -

    the name that will be sent to the KCS and appear in the Monitor

void setChannelDimensions(uint32_t width, uint32_t height)

Set the width and height of this channel.

Parameters
  • width -

    the width of this channel in pixels

  • height -

    the height of this channel in pixels

void setChannelOrigin(int ox, int oy)

Set the origin of this channel.

Parameters
  • ox -

    the x origin relative to the x origin of the frame to which this channel belongs to.

  • oy -

    the y origin relative to the y origin of the frame to which this channel belongs to.

void setDataSize(uint32_t dataSize)

Set the size - in bytes - of a pixels worth of data in this channel.

For example - if for each pixel this channel contains 4-channel color values stored as float values the size would be 4 * sizeof(float) and thus setDataSize(16).

Parameters
  • dataSize -

    the size in bytes of a pixel of data.

void setChannelID(uint16_t channelID)

Set the channel ID to identify this channel within a frame.

Parameters
  • channelID -

    the channel ID for this channel.

void setSampleRate(const float *sampleRate)
const uint8_t *frameUUID() const

Get the unique 128 bit identifier that is assigned to the frame this channel is a member of.

Return
a pointer to the start of the 16 uint8_t array that contains the unique frame ID.

uint16_t channelID() const
uint32_t channelHeight() const
uint32_t channelWidth() const
int channelXOrigin() const
int channelYOrigin() const
uint32_t channelDataSize() const
const std::string &channelName() const
uint32_t channelNameLength() const
const float *sampleRate() const
class NewChannelMessage_v2
#include <NewChannelMessage.h>

The NewChannelMessage_v2 class encapsulates the message sent to Katana indicating that a new channel should be reserved in the Catalog for a given frame.

The NewChannelMessage message should be sent down the KatanaPipe after a NewFrame message has been sent as the NewFrame message will reserve the frame in the Catalog.

A channel represents a given output pass by a renderer, such as the primary colour pass, id pass, depth pass P pass etc. The channel also defines the pixel layout of subsequent DataMessages.

Each NewChannelMessage object must be created with with reference to a valid unique frame ID so Katana will know which frame the channel belongs to.

Inherits from Foundry::Katana::NewChannelMessage

Public Types

enum PixelLayout

Values:

ARGB = 0
RGBA = 1
UNDEFINED = 0xFF

Public Functions

NewChannelMessage_v2(const uint8_t *frameID, uint16_t channelID = 0, PixelLayout pixelLayout = ARGB, uint32_t height = 0, uint32_t width = 0, int xorigin = 0, int yorigin = 0, float sampleRate1 = 0.0, float sampleRate2 = 0.0, uint32_t dataSize = 0)

Create a new instance of a NewChannelMessage specifying a pointer to a 16 byte array that will contain a unique frame ID.

The default for other values will create a new channel belonging to the specified frame with all values set to 0 and an empty string for the channel name.

See
setChannelName()
Parameters
  • frameID -

    a pointer to a 16 byte array containing a unique 128 bit frame ID.

  • channelID -

    an ID number to identify this channel within the frame. (This can just be sequential from zero).

  • pixelLayout -

    the order of components for all pixels.

  • height -

    the height of this channel in pixels.

  • width -

    the width of this channel in pixels.

  • xorigin -

    the x origin of this channel relative to the frame’s x origin

  • yorigin -

    the y origin of this channel relative to the frame’s y origin.

  • sampleRate1 -

    sampleRate1

  • sampleRate2 -

    sampleRate2

  • dataSize -

    the size - in bytes - of a single pixel of data for this channel.

NewChannelMessage_v2(const NewFrameMessage &frame, uint16_t channelID = 0, PixelLayout pixelLayout = ARGB, uint32_t height = 0, uint32_t width = 0, int xorigin = 0, int yorigin = 0, float sampleRate1 = 0.0, float sampleRate2 = 0.0, uint32_t dataSize = 0)

Create a new instance of NewChannelMessage_v2 message using an existing NewFrame object to obtain the unique frame ID.

The default constructor will create a new channel belonging to the specified frame with all values set to 0 and an empty string for the channel name.

Note: the NewChannelMessage_v2 object will NOT maintain a reference to NewFrameMessage or assume ownership of it.

See
setChannelName()
Parameters
  • frame -

    an existing NewFrameMessage object

  • channelID -

    an ID number to identify this channel within the frame. (This can just be sequential from zero).

  • pixelLayout -

    the order of components for all pixels.

  • height -

    the height of this channel in pixels.

  • width -

    the width of this channel in pixels.

  • xorigin -

    the x origin of this channel relative to the frame’s x origin

  • yorigin -

    the y origin of this channel relative to the frame’s y origin.

  • sampleRate1 -

    sampleRate1

  • sampleRate2 -

    sampleRate2

  • dataSize -

    the size - in bytes - of a single pixel of data for this channel.

virtual ~NewChannelMessage_v2()

Destroy the NewChannelMessage_v2 instance.

void setPixelLayout(PixelLayout pixelLayout)

Sets the pixel layout for all DataMessages that will be sent by the renderer for this channel/AOV.

Parameters
  • pixelLayout -

    the pixel layout that will be sent.

PixelLayout pixelLayout() const
class NewFrameMessage
#include <NewFrameMessage.h>

The NewFrameMessage class encapsulates the message sent to the Katana Catalog Server (KCS) to specify that a new frame should be reserved in the Catalog.

The NewFrameMessage should be sent down the KatanaPipe first to reserve a frame in the Catalog. A frame may contain zero or more channels. Channels then contain the actual data output by the renderer.

A frame represents the collection of these channels at a point in time.

Each NewFrameMessage object will be created with a unique 128 bit identifier that will identify the frame being rendered to Katana.

Inherits from Foundry::Katana::Message

Public Functions

NewFrameMessage(float frameTime = 0.0, uint32_t height = 0, uint32_t width = 0, int xorigin = 0, int yorigin = 0)

Create a new NewFrameMessage.

The default constructor will create a NewFrameMessage object with a unique frame id and all other values initialised to 0.

The frame’s name will be initialised to an empty string.

See
setFrameName()
Parameters
  • frameTime -

    the point in time this frame represents

  • height -

    the height in pixels of this frame

  • width -

    the width in pixels of this frame

  • xorigin -

    the xorigin relative to the lower left corner of the screen

  • yorigin -

    the yorigin relative to the lower left corner of the screen.

virtual ~NewFrameMessage()

Destroy the NewFrameMessage object.

int setFrameName(const std::string &name)

Set the human readable name that will appear in the name column of the Katana Catalog.

The maximum number of characters that can be specified in name is 8000.

Return
0 if the name was set successfully, otherwise nonzero, if nonzero is returned the existing name will remain unchanged.
Parameters
  • name -

    the name that will be sent to the KCS and appear in the Catalog

void setFrameTime(float time)

Set the frame time.

Parameters
  • time -

    the point in time this frame represents.

void setFrameDimensions(uint32_t width, uint32_t height)

Set the width and height of this frame.

Parameters
  • width -

    the width of this frame in pixels

  • height -

    the height of this frame in pixels

void setFrameOrigin(int ox, int oy)

Set the origin of this frame.

Parameters
  • ox -

    the x origin relative to the lower left corner of the screen

  • oy -

    the y origin relative to the lower left corner of the screen.

const uint8_t *frameUUID() const

Get the unique identifier for this frame.

Return
a pointer to the start of the 16 byte array that contains the unique frame ID.

uint32_t frameHeight() const
uint32_t frameWidth() const
int frameXOrigin() const
int frameYOrigin() const
float frameTime() const
const std::string &frameName() const
uint32_t frameNameLength() const