HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
IMG_TileDevice.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: IMG_TileDevice.h ( IMG Library, C++)
7  *
8  * COMMENTS: Class to define tile based I/O for mantra.
9  * When writing an image which has fields, the data sent to
10  * writeTile will not be interlaced. It's the responsibility of
11  * the device to put in the appropriate data to the other fields.
12  */
13 
14 #pragma once
15 
16 #ifndef __IMG_TileDevice__
17 #define __IMG_TileDevice__
18 
19 #include "IMG_API.h"
20 #include <UT/UT_Rect.h>
21 #include <UT/UT_String.h>
22 #include <UT/UT_StringArray.h>
23 #include "IMG_FileTypes.h"
24 #include "IMG_Tags.h"
25 
26 class UT_WorkBuffer;
27 class IMG_Raster;
28 class IMG_Format;
29 class IMG_TileInterface;
30 class IMG_TileOptions;
31 class IMG_TileOptionList;
32 class UT_Options;
33 
35 public:
37  virtual ~IMG_TileDevice();
38 
40  {
41  IMG_TILE_BOTTOM_FIRST = 0,
42  IMG_TILE_RANDOM_ORDER = 1,
43  IMG_TILE_TOP_FIRST = 2,
44  IMG_TILE_HILBERT = 3
45  };
46 
47  typedef IMG_TileDevice *(*IMG_TileDeviceCreator)(const char *filename,
48  const UT_Options *options);
49 
50  /// Create a new device based on the filename. This checks:
51  /// - "null:" - Null device
52  /// - "imdisplay:" - MPlay device
53  /// - etc.
54  /// If no devices match exactly, the file device will be opened.
55  static IMG_TileDevice *newDevice(const char *filename,
56  const UT_Options *options = NULL);
57 
58  /// Returns true if filename represents a special device, not a regular
59  /// file, i.e. everything that newDevice has a special case for.
60  static bool isSpecialFileName(const char *filename);
61 
62  /// Returns true if filename represents a null device,
63  /// i.e. it will ignore everything sent to it.
64  /// This is useful for avoiding work that will be ignored.
65  static bool isNullDeviceName(const char *filename);
66 
67  /// Register a custom image device. The label should be specified @b
68  /// without the colon (':'). For example: @code
69  /// registerDevice(createSocket, "socket");
70  /// @endcode
71  /// The creator function will be called from newDevice() with the
72  /// filename/options passed. newDevice() will invoke the creator if the
73  /// filename @b begins with the label. For example, the following would
74  /// invoke the socket device registered above: @code
75  /// newDevice("socket:{'port':43}", NULL);
76  /// @endcode
77  /// @note This will replace any existing device
78  static void registerDevice(IMG_TileDeviceCreator creator,
79  const char *label);
80  /// Unregister a custom device
81  static void unregisterDevice(const char *label);
82 
83  /// @{
84  /// Static methods to allocate new devices of built-in device types
85  static IMG_TileDevice *newFileDevice();
86  static IMG_TileDevice *newNullDevice();
87  static IMG_TileDevice *newMPlayDevice(int from_middle=1);
88  static IMG_TileDevice *imdisplayFileDevice(const char *filename);
89  static IMG_TileDevice *newSocketDevice(const char *host);
90  /// @}
91 
92  /// @{
93  /// Replace the creators for the file or mplay devices.
94  /// @note The signatures for the constructors are different than the
95  /// callbacks uses in @c registerDevice().
96  static void setFileDevCreator(IMG_TileDevice *(*creator)());
97  static void setMPlayDevCreator(IMG_TileDevice *(*creator)(int ));
98  /// @}
99 
100  /// @{
101  /// Query information about the tile device
102  virtual const char *className() const = 0;
103  virtual void getDescription(UT_WorkBuffer &wbuf) const;
104  /// @}
105 
106  // The visible region is inclusive (i.e. there are (r-l+1) pixels per scan)
107  // Setting the visible region should be done before the image is opened.
108  SYS_DEPRECATED_REPLACE(16.0, "setDeviceDataWindow")
109  void setVisibleRegion(int l, int r, int b, int t);
110 
111  // The region is always bigger or equal to the visible region. It
112  // represents the region which needs to be "rendered". The renderable
113  // region is broken up into tiles of the tile size specified.
114  SYS_DEPRECATED_REPLACE(16.0, "setDeviceRenderWindow")
115  void setRenderSize(int rwidth, int rheight);
116 
117  /// Set the data window
118  void setDeviceDataWindow(const UT_DimRect &w)
119  { myDataWindow = w; }
120 
121  /// Set the window of pixels that need to be rendered
122  /// The render window is always bigger or equal to the data window. It
123  /// might be larger due to pixel filters (i.e. samples outside the data
124  /// window might need to be computed for filtering). The difference
125  /// between the data window and the render window size is used to determine
126  /// filter width.
128  { myRenderWindow = w; }
129 
130  /// Open the device
131  virtual int open(const IMG_TileOptions &info,
132  int xres, int yres,
133  int tile_device, int tile_height,
134  fpreal aspect) = 0;
135 
136  /// The default implementation will just open the first entry of the flist
137  /// by calling open().
138  virtual int openMulti(
139  IMG_TileOptionList &flist,
140  int xres, int yres,
141  int tile_width, int tile_height,
142  fpreal aspect);
143 
144  virtual void setWhitePoint(fpreal white);
145 
146  /// Allow the device to perform any "checkpointing" needed. This is
147  /// equivalent to "flushing" the device.
148  virtual void checkpoint();
149 
150  // where the render originated from, to provide a half-decent name to ip.
151  void setRenderSourceName( const char *name )
152  { myRenderSourceName.harden(name); }
153  const char *getRenderSourceName() const
154  { return myRenderSourceName; }
155 
156  /// After the open() is called, then it's possible to query the data type
157  /// that the device expects.
158  int getFileCount() const { return myFileCount; }
159  IMG_DataType getDataType(int idx=0) const;
160  bool isRandomAccess() const { return myRandomAccess; }
161 
162  /// Query tile width parameters
163  int getTileWidth() const { return myTileWidth; }
164  int getTileHeight() const { return myTileHeight; }
165  int getTileCountX() const { return myTileCountX; }
166  int getTileCountY() const { return myTileCountY; }
167 
168  // Default is to return IMG_RGBA
169  IMG_ColorModel getColorModel(int idx=0) const;
170 
171  IMG_DataType *getDataTypes() { return myDataType; }
172  IMG_ColorModel *getColorModels() { return myColorModel; }
173 
174  // Writes a custom tag to the device. The tag must have a name, and some
175  // number of string values (zero is acceptable).
176  virtual void writeCustomTag(const char *tagname, int size,
177  const char *const *values);
178 
179  // Short cut method to write a well-known tag.
180  void writeKnownTag(IMG_TagType tag_id, int size,
181  const char *const *values)
182  {
183  writeCustomTag(IMGtagName(tag_id), size, values);
184  }
185 
186 
187  /// The data written is in the format specified by the IMG_ColorModel and
188  /// IMG_DataType parameters in the open. The size of the tile is smaller
189  /// or equal to the sizes specified in the open. If the device was
190  /// opened using openMulti(), the data is provided as a sequence of
191  /// planes - first all pixels for plane 0, then all pixels for plane 1,
192  /// etc.
193  ///
194  /// The rectangle spectified by @c x0, @c x1, @c y0 and @c y1 is an
195  /// inclusive rectangle. That is, the number of pixels in @c data is:
196  /// @c (x1-x0+1)*(y1-y0+1).
197  ///
198  /// The first pixel in the data buffer is the bottom left corner of the
199  /// tile (i.e. @c (x0,y0)).
200  ///
201  /// The rectangle specified is also relative to the data window. So, to
202  /// offset to get the absolute pixel location you need to take the data
203  /// window (getDataWindow()) into account. You can also use the
204  /// convenience methods @c getDataX() and getDataY(). For example: @code
205  /// unsigned pixel_x0 = x0 + getDataX();
206  /// unsigned pixel_x1 = x1 + getDataX();
207  /// unsigned pixel_y0 = y0 + getDataY();
208  /// unsigned pixel_y1 = y1 + getDataY();
209  /// @endcode
210  virtual int writeTile(const void *data,
211  unsigned x0, unsigned x1,
212  unsigned y0, unsigned y1) = 0;
213 
214  /// This is just for sending sample data from Mantra to Houdini
215  /// via TIL_TileMPlay.
216  /// data contains nsamples tuples of floats_per_sample floats
217  /// samples contains nsamples (x,y,pixel_sample) tuples
218  virtual bool writeSamples(
219  int nsamples,
220  int floats_per_sample,
221  const UT_Vector3T<int> *samples,
222  const float *data)
223  {
224  UT_ASSERT_MSG(0, "Should be implemented by subclass in relevant cases!");
225  return false;
226  }
227 
228  virtual void flush();
229 
230  virtual int close(bool keep_alive=false) = 0;
231 
232  // If the flush method is unsafe for multi-processing (or very costly), the
233  // device should return 1 here.
234  virtual int unsafeFlush();
235 
236  /// The renderer will ask us for the next tile location to be rendered.
237  /// We give it the location (in renderable region coordinates). The
238  /// function returns true if this is a valid tile, otherwise false.
239  /// The tile mode maps to the enum of bottom/top first or random order.
240  /// (tx,ty) will be the unique tile index tuple, between (0,0) inclusive
241  /// and (myTileCountX,myTileCountY) exclusive.
242  ///
243  /// NOTE: xl, xr, yb, and yt, are *all* inclusive!
244  /// Also, xl <= yr and yb <= yt if the return value is true,
245  /// i.e. at least one pixel.
246  virtual bool getNextTile(int &xl, int &xr, int &yb, int &yt,
247  int &tx, int &ty);
248 
249  // Returns true if a tile has been clicked; otherwise, false. If a tile
250  // has been clicked then tx and ty will be set to that tile's coordinates;
251  // otherwise, the values of tx and ty are undefined.
252  // The radius is in pixels.
253  virtual bool getClickedTile(int &tx, int &ty, float &radius) const;
254 
255  virtual void resetTileRequestor();
256  virtual int getTileMode() const;
257 
258  virtual void terminateOnConnectionLost(bool ) {}
259 
260  // Whether this object wants the Houdini HScript port to be written
261  // to it via writeCustomTag("houdiniportnum", ...)
262  virtual bool wantsHoudiniPort() const { return false; }
263 
264  /// If this tile device is interactive (i.e. a flipbook), this method
265  /// should return true. When mantra runs in batch-mode, opening an
266  /// interactive device will fail.
267  virtual bool isInteractive() const { return false; }
268 
269  /// @{
270  /// Accessor
271  int xres() const { return myDisplayWindow.width(); }
272  int yres() const { return myDisplayWindow.height(); }
273  /// @}
274 
275  // Passes style information to this tile device so it can be sent out
276  // later on.
277  virtual void setStyleSheets(UT_StringArray&) {}
278 
279  /// Subclasses can override this method if they respond to mouse clicks.
280  /// x and y should be set to the mouse position (in pixels) if the mouse
281  /// has been clicked. The method returns true if the mouse has been
282  /// clicked; otherwise, false. If the method returns false then the
283  /// values of x and y are undefined.
284  virtual bool getMouseClickPosition(int &x, int &y) const
285  { return false; }
286 
287  /// Subclasses can override this method if they respond to mouse clicks
288  /// and specify a radius for the click.
289  virtual float getMouseClickRadius() const
290  { return -1.0f; }
291 
292 protected:
293  // The sub-class must call this function to initialize the base class
294  // correctly.
295  void setResolution(int xres, int yres,
296  int tilewidth, int tileheight,
297  int tile_order = IMG_TILE_BOTTOM_FIRST);
298 
299  void setModel(const IMG_TileOptions &finfo);
300  void setModel(IMG_TileOptionList &flist);
301  void setModel(const IMG_DataType *dt, const IMG_ColorModel *cm);
302 
303  // Some random access devices may want to tell the renderer which tile to
304  // render next. This function will get the coordinates of the tile (i.e.
305  // if there are N tiles in X and M tiles in Y, tx is (0,N) and ty is (0,M)
306  void mapImageToTile(int ix, int iy, int &tx, int &ty);
307  void getTileBounds(int tx, int ty,
308  int &xl, int &xr, int &yb, int &yt);
309 
310  bool hasDataWindow(int full_xres, int full_yres) const;
311  int getDataX() const { return myDataWindow.x1(); }
312  int getDataY() const { return myDataWindow.y1(); }
313  int getDataWidth() const { return myDataWindow.width(); }
314  int getDataHeight() const { return myDataWindow.height(); }
315 
316  /// Specify the desired tile order.
317  void setTileOrder(IMG_TILE_ORDER tile_order)
318  { myRandomAccess = tile_order; }
319 
320  /// In the open method, the sub-class should set the file count
321  void setFileCount(int count)
322  { myFileCount = count; }
323 
324  /// Set the tile width
325  void setTileSize(int width, int height);
326 
327  SYS_DEPRECATED_REPLACE(16.0, "dataWindow()")
328  UT_InclusiveRect getDataWindow() const;
329 
330  /// @{
331  /// Accessors to data, display render windows
332  const UT_DimRect &dataWindow() const { return myDataWindow; }
333  const UT_DimRect &displayWindow() const { return myDisplayWindow; }
334  const UT_DimRect &renderWindow() const { return myRenderWindow; }
335  /// @}
336 
337 private:
338  fpreal myAspectRatio;
339  int myFileCount;
340  int myTileWidth, myTileHeight;
341  UT_DimRect myDataWindow;
342  UT_DimRect myDisplayWindow;
343  UT_DimRect myRenderWindow;
344  IMG_TILE_ORDER myRandomAccess; // If device supports random access
345 
346  int myClickedTileXY[2];
347  float myClickedRadius;
348  int myFilterX, myFilterY;
349  int myTileCountX, myTileCountY;
350  int myRandomCheck;
351  IMG_DataType *myDataType;
352  IMG_ColorModel *myColorModel;
353  IMG_TileInterface *myTiles;
354  UT_String myRenderSourceName;
355 };
356 
357 #endif
const UT_DimRect & displayWindow() const
int getDataWidth() const
int xres() const
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2544
void setTileOrder(IMG_TILE_ORDER tile_order)
Specify the desired tile order.
virtual float getMouseClickRadius() const
typedef void(APIENTRYP PFNGLCULLFACEPROC)(GLenum mode)
int getDataHeight() const
const UT_DimRect & renderWindow() const
void writeKnownTag(IMG_TagType tag_id, int size, const char *const *values)
int yres() const
GLint y
Definition: glcorearb.h:102
GLsizeiptr size
Definition: glcorearb.h:663
virtual bool getMouseClickPosition(int &x, int &y) const
GLint GLsizei width
Definition: glcorearb.h:102
virtual void setStyleSheets(UT_StringArray &)
#define SYS_DEPRECATED_REPLACE(__V__, __R__)
#define IMG_API
Definition: IMG_API.h:10
IMG_API UT_StringHolder IMGtagName(int id)
int getTileCountY() const
virtual void terminateOnConnectionLost(bool)
virtual bool writeSamples(int nsamples, int floats_per_sample, const UT_Vector3T< int > *samples, const float *data)
void setDeviceRenderWindow(const UT_DimRect &w)
int getDataY() const
void setRenderSourceName(const char *name)
IMG_DataType
Definition: IMG_FileTypes.h:17
int getFileCount() const
IMG_DataType * getDataTypes()
virtual bool isInteractive() const
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1601
GLboolean * data
Definition: glcorearb.h:130
GLuint const GLchar * name
Definition: glcorearb.h:785
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1221
virtual int open(float queuesize)
GLint GLsizei count
Definition: glcorearb.h:404
GLsizei samples
Definition: glcorearb.h:1297
GLint GLsizei GLsizei height
Definition: glcorearb.h:102
double fpreal
Definition: SYS_Types.h:269
A map of string to various well defined value types.
Definition: UT_Options.h:42
bool isRandomAccess() const
IMG_TagType
Definition: IMG_Tags.h:20
void setFileCount(int count)
In the open method, the sub-class should set the file count.
virtual void close()
int getTileHeight() const
virtual bool wantsHoudiniPort() const
IMG_ColorModel
Definition: IMG_FileTypes.h:53
GLint GLenum GLint x
Definition: glcorearb.h:408
int getTileWidth() const
Query tile width parameters.
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:856
const char * getRenderSourceName() const
int getDataX() const
GLboolean r
Definition: glcorearb.h:1221
#define const
Definition: zconf.h:214
int getTileCountX() const
#define UT_ASSERT_MSG(ZZ, MM)
Definition: UT_Assert.h:105
IMG_ColorModel * getColorModels()