ISoftBucket
Functions
void |
|
void |
|
int |
|
int |
Detailed Description
-
class ISoftBucket : public RED::IREDObject
Interface to control image areas to process by the software tracer.
@related function RED::IViewpointRenderList::SetViewpointSoftBucketCallback
This interface is received as a parameter of the callback defined by RED::SOFT_BUCKET_CALLBACK. It lets the callee control the current pixel regions being processed by the software ray-tracer.
A bucket is a 32 x 32 pixel region. It’s identified by its lower left corner coordinates in the image. A bucket is internally automatically clamped to the image border limits by the engine.
The user of this interface must take care of keeping a workload for each thread otherwise, threads may end if they don’t find anything to work on. A basic rule for this is to make sure that the list of buckets to calculate contains more entries than the number of calculating threads we have.
Two threads can’t work on the same bucket at different feedback levels at the same time, so to occupy ‘n’ threads, the list of buckets to calculate must always contain at least ‘n’ entries.
Public Functions
-
virtual RED_RC AddBucket(int iX, int iY, int iMinLevel) = 0
Adds a bucket to the list of bucket to process.
The bucket is added for all software ray-tracer feedback levels in [ 0, iMinLevel ]. Level 5 corresponds to the complete bucket calculations.
( iX, iY ) coordinates are expressed relatively to the rendered viewpoint’s viewport ( 0, 0 ) coordinate, that may differ from the window or VRL origin if the viewport is not anchored at the origin.
- Parameters
iX – Bucket relative lower left corner x pixel coordinate. Must be a multiple of 32.
iY – Bucket relative lower left corner y coordinate. Must be a multiple of 32.
iMinLevel – Feedback levels to calculate for this level. Must be in [ 0, 5 ].
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter. This may happen if ( iX, iY ) are not in the rendered viewport coordinates or if( ( iX, iY ) are not in the rendered window coordinate range or if ( iX, iY ) are not a multiple of 32 pixels from the origin of the viewport of the rendered camera,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if the soft bucket callback is used in a context for which there’s no image output that can be produced (for example the calculation of an GI cache or a pixel analysis),
RED_FAIL otherwise.
-
virtual void GetCompletedBucket(int &oX, int &oY, int &oLevel) const = 0
Gets the last completed bucket calculation.
Each time the RED::SOFT_BUCKET_CALLBACK is called, this is because a bucket’s calculation has been completed at a given feedback level (which does not mean a bucket at all levels). This is true except on startup.
This method returns the coordinates of the bucket that was completed and the corresponding depth if was calculated for.
- Parameters
oX – Bucket lower left corner x coordinate. -1 if no bucket was calculated.
oY – Bucket lower left corner y coordinate. -1 if no bucket was calculated.
oLevel – Level of feedback for which the calculation ended. -1 if no bucket was calculated.
-
virtual void GetCompletedBucketLuminance(double &oLuminanceMin, double &oLuminanceMax, double &oLuminanceAverage, double &oLuminanceLogAverage) const = 0
Returns the completed bucket luminance informations.
This method returns the actual luminance informations stored for the bucket. Luminance values will vary with the calculated bucket level, until the last level is reached, for which the final luminance values for this bucket are returned.
Returned informations are set to zero if we have no bucket calculated yet.
- Parameters
oLuminanceMin – Minimal luminance information for this bucket.
oLuminanceMax – Maximal luminance information for this bucket.
oLuminanceAverage – Average luminance for all calculated bucket pixels.
oLuminanceLogAverage – Average logarithmic luminance for all calculated bucket pixels.
-
virtual int GetMinRemainingBucketsCount() const = 0
Gets a number of buckets that are waiting to be computed.
The value returned by this method can be smaller than the actual number of buckets that are left to compute. For performance reasons, we do not parse the lists of buckets at each refinement depth to get the exact list of unique buckets that needs to be calculated.
Instead we return the largest list of buckets that remain for computation among the lists that are stored for each feedback level.
- Returns
A number of remaining buckets, which can be smaller than the real exact number of buckets that are left to compute.
-
virtual int GetThreadsCount() const = 0
Returns the number of threads used by the software ray-tracer.
- Returns
The number of calculation threads.
-
virtual RED_RC AddBucket(int iX, int iY, int iMinLevel) = 0
