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 C{data} will remain under the control of the caller unless the user provides an C{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 C{FnPixelDataDeleter} it is not safe to access the data buffer once C{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 C{KatanaPipe::send()} is called.
- Note
- If C{setData()} was called with an C{FnPixelDataDeleter} function this method will return NULL after a call to C{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 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¶
-
-
bool