HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TIL_RasterFilter.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: TIL_MiscHelper.h (TIL Library, C++)
7  *
8  * COMMENTS: A generic interface to provide filters for rasters with
9  * multiple raster planes. Examples of this might include
10  * denoisers which read from multiple input planes and write to
11  * multiple output planes.
12  *
13  */
14 
15 #ifndef TIL_MiscHelper_H
16 #define TIL_MiscHelper_H
17 
18 #include "TIL_API.h"
19 #include "TIL_Defines.h"
20 
21 #include <SYS/SYS_Visibility.h>
22 #include <UT/UT_Options.h>
23 #include <UT/UT_StringArray.h>
24 #include <UT/UT_StringHolder.h>
25 #include <UT/UT_StringMap.h>
26 #include <UT/UT_UniquePtr.h>
27 
28 class PXL_Raster;
29 class UT_Options;
30 
31 /// Apply arbitrary filters to PXL_Raster image(s).
32 ///
33 /// The DSO must implement "newRasterFilter" function which should create new
34 /// filters by calling TIL_RasterFilter::registerFactory(). Image filters will
35 /// be searched for in $HOUDINI_DSO_PATH/img_filter.
36 ///
37 /// When the filter is instantiated, the caller will initialize the filter
38 /// calling @c setOptions. This is only called one time, though the filter may
39 /// be invoked multiple times.
40 ///
41 /// Prior to invoking the filter, the @c reset() method will be called. This
42 /// lets the filter reset any information that changes from run to run.
43 ///
44 /// The caller will then set up any optional read-only auxilliary rasters the
45 /// filter may need for processing. That is, the caller will call @c
46 /// setAuxPlane zero or more times.
47 ///
48 /// After the filter is reset and auxilliary planes are added, the @c apply()
49 /// method will finally be called. This should modify the raster passed in to
50 /// create the resulting image. It's possible the apply() method may be called
51 /// multiple times before reset() is called again.
53 {
54 public:
56 
57  /// The factory to define a filter
59  {
60  virtual ~Factory();
61  virtual const UT_StringHolder &name() const = 0;
62  virtual const UT_StringHolder &label() const = 0;
63  virtual TIL_RasterFilterPtr newFilter() const = 0;
64  };
65 
66  /// @{
67  /// Constructor/Destructor
69  virtual ~TIL_RasterFilter() {};
70  /// @}
71 
72  /// Register a new factory. Set HOUDINI_DSO_ERROR=1 to get information on
73  /// why the filter might not be installed.
74  static void registerFactory(UT_UniquePtr<Factory> factory);
75 
76  /// Get a list of all the filters
77  static void getFilters(UT_Array<const Factory *> &filters);
78 
79  // Allocate a filter of a given name
80  static TIL_RasterFilterPtr allocFilter(const UT_StringRef &name);
81 
82  /// For debugging
83  virtual const char *className() const = 0;
84 
85  /// Initiaze the filter with user specified options. This method is only
86  /// called once. If the filter isn't valid, the @c myErrorString member
87  /// should be set to a meaningful error and the function should return
88  /// false.
89  ///
90  /// Aside from setting any specific options, this is also the time you
91  /// should build myAuxPlaneNames. This lets the caller know which extra
92  /// AOVs you can read from. Not all of them may exist, but this lets the
93  /// caller know which planes you can look at.
94  virtual bool setOptions(const UT_Options &options) { return true; }
95 
96  /// Set up an auxilliary plane. This is a raster which isn't actually
97  /// modified, but is used in the filtering (for example a mask). The
98  /// caller looks at the @c myAuxPlaneNames list to see which rasters you
99  /// might require. If they are available, they will be stashed in this
100  /// array.
101  void setAuxPlane(const UT_StringHolder &planename,
102  const PXL_Raster *raster)
103  {
104  myAuxPlanes[planename] = raster;
105  }
106 
107  /// Returns false if fail
108  virtual bool apply(PXL_Raster *raster) = 0;
109 
110  /// Reset and get ready for a new filter. If you subclass this method,
111  /// please make sure to call the base class method.
112  virtual void reset()
113  {
114  myAuxPlanes.clear();
115  }
116 
117  /// Get the list of aux plane names
119  { return myAuxPlaneNames; }
120 
121  /// Get stored error msg in case apply() fails. Sub-classes can set @c
122  /// myErrorString to something meaningful for the caller.
124  { return myErrorString; }
125 
126  /// If the filter can run in a few milliseconds, you can try returning
127  /// true.
128  virtual bool isInteractive() const { return false; }
129 
130 protected:
134 };
135 
137 
138 extern "C" {
139  /// DSO function called. This function can register one or more filters.
140  /// Only filters which are supported should be registered.
142 }
143 
144 #endif
UT_StringHolder myErrorString
SYS_VISIBILITY_EXPORT void newRasterFilter()
UT_StringArray myAuxPlaneNames
GLuint const GLchar * name
Definition: glew.h:1814
#define SYS_VISIBILITY_EXPORT
void setAuxPlane(const UT_StringHolder &planename, const PXL_Raster *raster)
const UT_StringHolder & getErrorString() const
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:33
const UT_StringArray & getAuxPlaneNames() const
Get the list of aux plane names.
virtual bool isInteractive() const
virtual void reset()
GLuint GLsizei GLsizei GLchar * label
Definition: glew.h:8986
TIL_RasterFilter::TIL_RasterFilterPtr TIL_RasterFilterPtr
virtual bool setOptions(const UT_Options &options)
A map of string to various well defined value types.
Definition: UT_Options.h:84
The factory to define a filter.
#define TIL_API
Definition: TIL_API.h:10
UT_StringMap< const PXL_Raster * > myAuxPlanes
UT_UniquePtr< TIL_RasterFilter > TIL_RasterFilterPtr
virtual ~TIL_RasterFilter()