3ds Max C++ API Reference
Loading...
Searching...
No Matches
GBuffer Class Referenceabstract

#include <gbuf.h>

+ Inheritance diagram for GBuffer:

Public Member Functions

virtual void SetRasterSize (int ww, int hh)=0
 
virtual int Width ()=0
 
virtual int Height ()=0
 
virtual int InitBuffer ()=0
 
virtual ULONG CreateChannels (ULONG channelMask)=0
 
virtual void DeleteChannels (ULONG channelMask)=0
 
virtual ULONG ChannelsPresent ()=0
 
virtual voidGetChannel (ULONG channelID, ULONG &chanType)=0
 
virtual GBufReaderCreateReader ()=0
 
virtual void DestroyReader (GBufReader *pRdr)=0
 
virtual GBufWriterCreateWriter ()=0
 
virtual void DestroyWriter (GBufWriter *pRdr)=0
 
virtual BOOL IsDefaultGBuffer ()
 
virtual void DeleteThis ()=0
 
virtual void Copy (GBuffer *gbfrom)=0
 
virtual void CopyScale (GBuffer *gbfrom, int cw=-1, int ch=-1)=0
 
virtual void Position (int srcy, int trgy, int srcx, int trgx, int trgw, int trgh)=0
 
virtual int NumberLayerRecords (int y)=0
 
virtual int GetLayerChannel (int y, int ichan, char *data)=0
 
virtual int CreateLayerRecords (int y, int num)=0
 
virtual int SetLayerChannel (int y, int ichan, char *data)=0
 
virtual void UpdateChannelMinMax ()=0
 
virtual BOOL GetChannelMin (int chan, void *data)=0
 
virtual BOOL GetChannelMax (int chan, void *data)=0
 
virtual NameTabNodeRenderIDNameTab ()=0
 
virtual Tab< float > & ImageBlurMultiplierTab ()=0
 
- Public Member Functions inherited from InterfaceServer
virtual UtilExport ~InterfaceServer ()
 Destructor.
 
virtual UtilExport BaseInterfaceGetInterface (Interface_ID id)
 
template<class InterfaceType >
InterfaceType * GetTypedInterface ()
 

Static Public Member Functions

static CoreExport void ColorById (int id, BMM_Color_24 &cOut)
 
- Static Public Member Functions inherited from MaxHeapOperators
static UtilExport voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e)
 Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned.
 
static UtilExport voidoperator new (size_t size, const char *filename, int line)
 New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
 New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned.
 
static UtilExport voidoperator new (size_t size, unsigned long flags)
 New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e, unsigned long flags)
 New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned.
 
static UtilExport voidoperator new[] (size_t size)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned.
 
static UtilExport voidoperator new[] (size_t size, const char *filename, int line)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects.
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned.
 
static UtilExport voidoperator new[] (size_t size, unsigned long flags)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned.
 
static UtilExport void operator delete (void *ptr)
 Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e)
 Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen.
 
static UtilExport void operator delete (void *ptr, const char *filename, int line)
 Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete (void *ptr, int block_type, const char *filename, int line)
 Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
 Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen.
 
static UtilExport void operator delete (void *ptr, unsigned long flags)
 Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
 Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen.
 
static UtilExport void operator delete[] (void *ptr)
 Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e)
 Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen.
 
static UtilExport void operator delete[] (void *ptr, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete[] (void *ptr, int block_type, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen.
 
static UtilExport void operator delete[] (void *ptr, unsigned long flags)
 Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown.
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
 Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown.
 
static UtilExport voidoperator new (size_t size, void *placement_ptr)
 Placement new operator.
 
static UtilExport void operator delete (void *ptr, void *placement_ptr)
 Placement delete operator.
 
static UtilExport voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary.
 
static UtilExport voidaligned_realloc (void *ptr, size_t size, size_t alignment)
 Reallocates memory on a specified alignment boundary.
 
static UtilExport void aligned_free (void *ptr)
 Frees a block of memory that was allocated with aligned_malloc/aligned_realloc.
 

Detailed Description

See also
Class GBufReader, Class GBufWriter, Image (G-Buffer) Channels, G-Buffer Channel Types, Class Bitmap.

class GBuffer : public InterfaceServer

Description:
This class is used by Bitmaps to implement an enhanced G-Buffer (providing more functionality than the 2.x G-Buffer). The new G-Buffer stores multiple layers at each pixel. The Virtual Frame Buffer includes a new spinner to the right of the "channels" drop down which lets you look at the different layers. (It only appears when there are G-Buffer channels present).

The multiple layers of the G-Buffer allow rendering effects to do better antialiasing and handling of transparency. The frontmost layer is still stored in the G-Buffer as full, screen-sized arrays, one for each channel. The subsequent layers are stored in a variable number of "layer records" all of which are the same size (which depends on which channels have been requested via the GBuffer::CreateChannels() function). Even scenes with no transparency can have more than one layer at a given pixel. This can occur along the edges of an object, where the object partially covers some pixels, and another object (or objects) is visible in the remaining part of the pixel. Each visible face in the pixel will be represented by a fragment. A given object will not always appear on the same layer. If it is the only object in a pixel it will be in the frontmost layer, but where it is partially occluded it will lie in a layer behind the occluding object.

Another way multiple layers can occur (aside from transparency) is when objects are given the "Render Occluded Objects" property in the object properties dialog. When an object has this property, it acts as if it were transparent, and objects behind it, though invisible, are rendered and stored in the G-Buffer.

Another G-Buffer layer is added to contain the background color in its color channel for any pixel which is not empty and on which the background gets evaluated. This means the background layer will be present behind transparent objects or objects with "render occluded" turned on. It will also be present along the edges of objects where the background is partially visible in the pixel. Note: This does not depend at all on having the GB_BG flag set. It is necessary to have the GB_COLOR channel, however.

All methods of this class are implemented by the System.

Note on RPF files: The following information relates to the layer storage scheme used in the 3ds Max RPF files.

The layer information for each scan line is stored as a series of run-encoded channels, each containing the same number of data elements, one per layer record. The first channel is a "psuedo-channel" that contains the x value for each layer record. If there are multiple layers for a given x, this will be reflected as several identical x values in a row.

For instance, if the x channel contained

5,6,7,7,8,8,8,9,10

And the Z channel contained

100, 100, 100,200, 100,200,300, 100, 100

This would mean at pixel 7 there are 2 layers, and pixel 8 there are 3 layers.

Pixel depths

5 100

6 100

7 100, 200

8 100, 200, 300

9 100

10 100

As an extra note regarding RPF files, a new data member was added to class RenderInfo, which is saved with the RPF (and RLA) files. In order to avoid getting out of sync with previous file format implementations a "version" word preceding the RenderInfo record has been added into the format. The version is set to a value that will distinguish it from the first word of the RenderInfo data, enabling it to determine the version. If we make further additions to RenderInfo in the future, the version will allow us to keep it straight. To load both older and newer RPF and RLA files correctly, the code that loads the RenderInfo been modified, and therefore any plugins and 3rd party code that read these files need to be changed. Here's the code:

#define RENDINFO_VERS1 1000
int RLAReader::ReadRendInfo(RenderInfo *ri) {
short vers;
if (fread(\&vers,sizeof(short),1,fd)!=1) return 0;
int size = sizeof(RenderInfo);
if (vers != RENDINFO_VERS1) {
// the old version didn't start with a version word, but
// with projType which is 0 or 1.
size -= sizeof(Rect); // The old record didn't have the region Rect.
fseek(fd,-sizeof(short),SEEK_CUR); // Undo the version read
}
if (ri) {
if (fread(ri,size,1,fd)!=1) return 0;
}
else
fseek(fd, size, SEEK_CUR);
return 1;
}
Box2 Rect
Definition: box2.h:192
Definition: bitmap.h:560

Member Function Documentation

◆ SetRasterSize()

virtual void SetRasterSize ( int  ww,
int  hh 
)
pure virtual
Remarks
This method is used internally to set the size of the G-Buffer.
Parameters:
int ww

The width to set in pixels.

int hh

The height to set in pixels.

◆ Width()

virtual int Width ( )
pure virtual
Remarks
Returns the width of the GBuffer.

◆ Height()

virtual int Height ( )
pure virtual
Remarks
Returns the height of the GBuffer.

◆ InitBuffer()

virtual int InitBuffer ( )
pure virtual
Remarks
Initializes the GBuffer. Call this method before writing to the buffer. If present, the GB_Z channels is set to -BIGFLOAT and the GB_NODE_RENDER_ID channel is set to 0xffff. The Render ID Name Table is cleared.
Returns
Nonzero on success; otherwise zero.
Sample Code:
GBuffer *gbuf = tobm->GetGBuffer();
if (gbuf) gbuf->InitBuffer();
Definition: gbuf.h:594
virtual int InitBuffer()=0

◆ CreateChannels()

virtual ULONG CreateChannels ( ULONG  channelMask)
pure virtual
Remarks
This method creates the specified channels in this G-Buffer.
Parameters:
ULONG channelMask

Specifies the channels to create. See Image (G-Buffer) Channels.
Returns
The channels that are currently present.

◆ DeleteChannels()

virtual void DeleteChannels ( ULONG  channelMask)
pure virtual
Remarks
This method delete specified channels.
Parameters:
ULONG channelMask

Specifies the channels to create. See Image (G-Buffer) Channels.

◆ ChannelsPresent()

virtual ULONG ChannelsPresent ( )
pure virtual
Remarks
Returns the channels that are currently present. See Image (G-Buffer) Channels.

◆ GetChannel()

virtual void * GetChannel ( ULONG  channelID,
ULONG &  chanType 
)
pure virtual
Remarks
Returns a pointer to the specified channel of the G-Buffer, and determines its type in terms of bits per pixel. NULL is returned if the channel can't be found.
Parameters:
ULONG channelID

The channel to get. See Image (G-Buffer) Channels ULONG& chanType

The channel type. See G-Buffer Channel Types.

◆ CreateReader()

virtual GBufReader * CreateReader ( )
pure virtual
Remarks
Creates and returns a pointer to a GBufReader object.

◆ DestroyReader()

virtual void DestroyReader ( GBufReader pRdr)
pure virtual
Remarks
Deletes the specified GBufReader object.
Parameters:
GBufReader *pRdr

Points to the reader to delete.

◆ CreateWriter()

virtual GBufWriter * CreateWriter ( )
pure virtual
Remarks
Creates and returns a pointer to a GBufWriter object.

◆ DestroyWriter()

virtual void DestroyWriter ( GBufWriter pRdr)
pure virtual
Remarks
Deletes the specified GBufWriter object.
Parameters:
GBufWriter *pRdr

Points to the writer to delete.

◆ IsDefaultGBuffer()

virtual BOOL IsDefaultGBuffer ( )
inlinevirtual
Remarks
Returns TRUE if this is a default G-Buffer; otherwise FALSE. A 'default' G-Buffer is one that 3ds Max itself creates. Since GBuffer is a virtual class a plug-in developer could create their own G-Buffers (for some very special purpose). In that case it would not be a 'default' G-Buffer and this method would return FALSE.
662{ return FALSE; }

◆ DeleteThis()

virtual void DeleteThis ( )
pure virtual
Remarks
Deletes this G-Buffer.

◆ Copy()

virtual void Copy ( GBuffer gbfrom)
pure virtual
Remarks
Copies the data from the specified G-Buffer to this one. This method maintains the multi-layer data correctly. The channels present in each G-Buffer must match.
Parameters:
GBuffer *gbfrom

Points to the source of the copy.

◆ CopyScale()

virtual void CopyScale ( GBuffer gbfrom,
int  cw = -1,
int  ch = -1 
)
pure virtual
Remarks
Copies the data from the specified G-Buffer and optionally scales its size while maintaining the multi-layer data correctly. This is used in Video Post whenever there is an input bitmap that is a different size than the current Video Post image dimensions.
Parameters:
GBuffer *gbfrom

Points to the source of the copy.

int cw=-1

The width for the copy. If -1 is specified the copy is the same size as the original.

int ch=-1

The height for the copy. If -1 is specified the copy is the same size as the original.

◆ Position()

virtual void Position ( int  srcy,
int  trgy,
int  srcx,
int  trgx,
int  trgw,
int  trgh 
)
pure virtual
Remarks
This method is used internally and is something that normally a developer shouldn't call directly. It is used inside the Bitmap routines for manipulating bitmaps. It takes a sub rectangle of the G-Buffer which has an upper left corner at (srcx,srcy), and dimensions of (trgw,trgh), and moves it to be positioned at (trgx,trgy). Portions of the G-Buffer outside of this rectangle are discarded.
Parameters:
int srcy

The source y location.

int trgy

The target y location.

int srcx

The source x location.

int trgx

The target x location.

int trgw

The target width.

int trgh

The target height.

◆ NumberLayerRecords()

virtual int NumberLayerRecords ( int  y)
pure virtual
Remarks
Returns the total number of layer records for the specified scan line. On each scan line there is a single array of layer records. Each layer record contains an x value which tells at what pixel it is located, and then all of the G-Buffer data that is being stored in this particular G-Buffer. The layer records for a given pixel all have the same x value, and are ordered front-to-back in scene depth.

This method is used by the RLA and RPF writer code. See /MAXSDK/SAMPLES/IO/RLA/RLA.CPP for an example.
Parameters:
int y

The zero based index of the scan line.

◆ GetLayerChannel()

virtual int GetLayerChannel ( int  y,
int  ichan,
char *  data 
)
pure virtual
Remarks
This method goes through all the layer records and pulls out the values for a particular channel into an array, which is handy for run-encoding when saving to a file.
Parameters:
int y

The zero based index of the scan line.

int ichan

The channel to check. See G-Buffer Channel Indices. When ichan=-1, it gives an array of the x values from each of the layer records.

char *data

Points to storage for the layer data.
Returns
TRUE on success; otherwise FALSE.

◆ CreateLayerRecords()

virtual int CreateLayerRecords ( int  y,
int  num 
)
pure virtual
Remarks
This method creates the specifed number of layer records for the scan line passed.
Parameters:
int y

The zero based index of the scan line.

int num

The number of records to create.
Returns
TRUE on success; otherwise FALSE.

◆ SetLayerChannel()

virtual int SetLayerChannel ( int  y,
int  ichan,
char *  data 
)
pure virtual
Remarks
Sets the layer record data for the specified channel for the scan line passed.
Parameters:
int y

The zero based index of the scan line.

int ichan

The channel to set. See G-Buffer Channel Indices. When ichan=-1, it sets an array of the x values from each of the layer records.

char *data

Points to storage for the layer data.
Returns
TRUE on success; otherwise FALSE.

◆ UpdateChannelMinMax()

virtual void UpdateChannelMinMax ( )
pure virtual
Remarks
This method searches the G-Buffer Z, UV and VELOC channels and stores the minimum and maximum values. This enables the GetChannelMin() and GetChannelMax() methods to work. This is called internally whey 3ds Max generates a G-Buffer. When developers get one from the renderer this method will already have been called.

◆ GetChannelMin()

virtual BOOL GetChannelMin ( int  chan,
void data 
)
pure virtual
Remarks
Retrieves the minimum value in the specified channel.
Parameters:
int chan

The channel to check. One of the following (the other channels are not supported):

GB_Z

Z-Buffer depth - float

GB_UV

UV coordinates - Point2

GB_VELOC

Velocity - Point2

void *data

Points to storage for the value to get.
Returns
TRUE if chan was valid and the value could be stored in data; otherwise FALSE.

◆ GetChannelMax()

virtual BOOL GetChannelMax ( int  chan,
void data 
)
pure virtual
Remarks
Retrieves the maximum value in the specified channel.
Parameters:
int chan

The channel to check. One of the following (the other channels are not supported):

GB_Z

Z-Buffer depth - float

GB_UV

UV coordinates - Point2

GB_VELOC

Velocity - Point2

void *data

Points to storage for the value to get.
Returns
TRUE if chan was valid and the value could be stored in data; otherwise FALSE.

◆ NodeRenderIDNameTab()

virtual NameTab & NodeRenderIDNameTab ( )
pure virtual
Remarks
This method returns a reference to the table of node names indexed by their NodeRenderId. See Class NameTab.

◆ ImageBlurMultiplierTab()

virtual Tab< float > & ImageBlurMultiplierTab ( )
pure virtual
Remarks
This method returns a reference to a table of floats. These are image blur multipliers indexed by NodeRenderID.

◆ ColorById()

static CoreExport void ColorById ( int  id,
BMM_Color_24 cOut 
)
static
Remarks
Gives the color corresponding to the id in the input. This function represents the color-id mapping that is done for
Parameters:
id

The material or object id for which the color is wanted

cOut

The output color BMM_Color_24 type.