RenderManAPI  24.0
RtxPlugin.h
Go to the documentation of this file.
1 /*
2 # ------------------------------------------------------------------------------
3 #
4 # Copyright (c) 2020 Pixar. All rights reserved.
5 #
6 # The information in this file (the "Software") is provided for the exclusive
7 # use of the software licensees of Pixar ("Licensees"). Licensees have the
8 # right to incorporate the Software into other products for use by other
9 # authorized software licensees of Pixar, without fee. Except as expressly
10 # permitted herein, the Software may not be disclosed to third parties, copied
11 # or duplicated in any form, in whole or in part, without the prior written
12 # permission of Pixar.
13 #
14 # The copyright notices in the Software and this entire statement, including the
15 # above license grant, this restriction and the following disclaimer, must be
16 # included in all copies of the Software, in whole or in part, and all permitted
17 # derivative works of the Software, unless such copies or derivative works are
18 # solely in the form of machine-executable object code generated by a source
19 # language processor.
20 #
21 # PIXAR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
22 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL PIXAR BE
23 # LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
24 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
25 # OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
26 # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. IN NO CASE WILL
27 # PIXAR'S TOTAL LIABILITY FOR ALL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
28 # THE USE OR PERFORMANCE OF THIS SOFTWARE EXCEED $50.
29 #
30 # Pixar
31 # 1200 Park Ave
32 # Emeryville CA 94608
33 #
34 # ------------------------------------------------------------------------------
35 */
36 
37 
38 #ifndef RTXPLUGIN_H
39 #define RTXPLUGIN_H
40 
41 #include "prmanapi.h" // for PRMANEXPORT
42 
43 class RixContext; // IWYU pragma: keep
44 
45 // An RtxPlugin class
46 class RtxPlugin
47 {
48 public:
49  RtxPlugin() {}
50  virtual ~RtxPlugin() {}
51 
53  struct Int2D
54  {
55  int X;
56  int Y;
57  };
58 
60  struct Tile2D
61  {
64  };
65 
76  struct TextureCtx
77  {
80 
82  unsigned int numLayers;
83 
89  struct layerSpec
90  {
91  const char* name;
92  unsigned numChannels;
93  } * *layers;
94 
97 
99  enum WrapMode
100  {
101  k_Black = 0,
104  } sWrap,
105  tWrap;
106 
108  enum DataType
109  {
110  k_Byte = 0,
112  } dataType;
113 
116  {
117  k_Single = 0,
120  } pyramidType;
121 
123  bool isLocked;
124 
127  unsigned int argc;
128  const char** argv;
129 
132  void* userData;
133 
134  // Version 2 API starts here
135 
136  // A plugin can request retry on error
137  // a fill may be aborted mid fill request
138  // during rerendering (resulting in incorrect fill data)
139  // Authors may request such errors during fill are retried
140  // during subsequent attempts to fill.
142  };
143 
146  virtual int Open(TextureCtx& tCtx) = 0;
147 
152  struct FillRequest
153  {
154  // This is the resolution of the image at a given MIP level
156 
157  // This is the tile index and tile size
159 
160  // This is a channel selection string. This string can be
161  // NULL if channel selection is not made by string.
162  const char* channelRefExpr;
163 
164  // This is the offset from zero for a given channel selection
165  // It is always zero if channelRefExpr is not NULL.
167 
168  // This is the number of channels we want to fill
170 
171  // The data (interleaved) with GetStride() channels
172  // that the plugin should write the tile results into
173  void* tileData;
174  };
175 
176  // The plugin should use the fillReq inputs to write to the
177  // tileData in the FillRequest. Return nonzero on errors.
178  virtual int Fill(TextureCtx& tCtx, FillRequest& fillReq) = 0;
179 
180  // The plugin should release all assets at Close()
181  virtual int Close(TextureCtx& tCtx) = 0;
182 };
183 
184 // A RixContext is provided to an RtxPlugin at
185 // creation time, so that the plugin may use
186 // services provided by the renderer.
187 #define RTXPLUGINCREATE \
188  extern "C" const PRMANEXPORT int RtxPluginVersion = 2; \
189  extern "C" PRMANEXPORT RtxPlugin* RtxPluginNew( \
190  RixContext* rixCtx, const char* pluginName)
191 #endif
virtual ~RtxPlugin()
Definition: RtxPlugin.h:50
A struct to define an X,Y coordinate.
Definition: RtxPlugin.h:53
TextureCtx provides initial defining properties for textures generated by this plugin.
Definition: RtxPlugin.h:76
int numChannels
Definition: RtxPlugin.h:169
Int2D offset
Definition: RtxPlugin.h:62
WrapMode
The wrap mode applied at the edges of max resolution.
Definition: RtxPlugin.h:99
Rix interfaces are obtained from an RixContext.
Definition: RixInterfaces.h:172
void * tileData
Definition: RtxPlugin.h:173
Definition: RtxPlugin.h:119
Int2D imgRes
Definition: RtxPlugin.h:155
unsigned int argc
Read-only texture args, they come in pairs, memory is owned by the renderer.
Definition: RtxPlugin.h:127
int channelOffset
Definition: RtxPlugin.h:166
struct RtxPlugin::TextureCtx::layerSpec ** layers
int numChannels
This is the total number of channels present.
Definition: RtxPlugin.h:79
Definition: RtxPlugin.h:103
Int2D maxRes
Definition: RtxPlugin.h:96
virtual int Close(TextureCtx &tCtx)=0
virtual int Open(TextureCtx &tCtx)=0
The Open() method is called the first time a texture() encounters the plugin and provides a unique ar...
unsigned numChannels
Definition: RtxPlugin.h:92
const char * channelRefExpr
Definition: RtxPlugin.h:162
Plugin fills in the names and channel-count of the layers associated with this texture.
Definition: RtxPlugin.h:89
PyramidType
What type of pyramid should be used?
Definition: RtxPlugin.h:115
enum RtxPlugin::TextureCtx::WrapMode sWrap
bool isLocked
Should the tile be locked while filling? (not thread safe?)
Definition: RtxPlugin.h:123
Definition: RtxPlugin.h:111
enum RtxPlugin::TextureCtx::PyramidType pyramidType
Tile2D tile
Definition: RtxPlugin.h:158
RtxPlugin()
Definition: RtxPlugin.h:49
Definition: RtxPlugin.h:110
A struct to define a 2D region.
Definition: RtxPlugin.h:60
Definition: RtxPlugin.h:46
const char * name
Definition: RtxPlugin.h:91
bool retryOnError
Definition: RtxPlugin.h:141
void * userData
The plugin can use this field to stash its own instance data.
Definition: RtxPlugin.h:132
unsigned int numLayers
The maximum # of layers this texture can access.
Definition: RtxPlugin.h:82
enum RtxPlugin::TextureCtx::WrapMode tWrap
int Y
Definition: RtxPlugin.h:56
Definition: RtxPlugin.h:117
Int2D minRes
The min,max resolution requested for this texture.
Definition: RtxPlugin.h:96
Int2D size
Definition: RtxPlugin.h:63
Definition: RtxPlugin.h:102
const char ** argv
Definition: RtxPlugin.h:128
Definition: RtxPlugin.h:101
enum RtxPlugin::TextureCtx::DataType dataType
int X
Definition: RtxPlugin.h:55
virtual int Fill(TextureCtx &tCtx, FillRequest &fillReq)=0
NOTE: multi-channel textures might receive a FillRequest of fewer than nchans with a channelOffset >=...
Definition: RtxPlugin.h:152
Definition: RtxPlugin.h:118
DataType
The type of the data provided by the texture.
Definition: RtxPlugin.h:108