RE/RE_OGLBufferObject.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Mark Alexander
 *      Side Effects
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        RE_OGLBufferObject.h ( RE Library, C++)
 *
 * COMMENTS:
 *   Buffer objects are merely registered chunks of memory that is
 *   managed by the graphics driver. Although the come in different
 *   flavours, they are all created and accessed in the same way.
 *
 *   One buffer object represents one type of data - texture coords,
 *   point positions, pixels or colors. There are two main types in terms
 *   of usage, vertex and pixel buffers.
 *
 *   1. Vertex-oriented buffers are used in lieu of glVertex, glNormal,
 *      glColor, etc.. They are much more efficient in that you can send
 *      a lot of data with one call, and you can update parts of the
 *      list instead of rewriting the entire list. They are used in
 *      conjunction with glDrawArrays() to create geometry. As an example:
 *
 *         RE_OGLVertexBuffer vBuf(nVertices);
 *         RE_OGLVertexBuffer texBuf(nVertices, 0); // 0 = gl_TexCoord[0]
 *
 *         vBuf.setData(vertex_list);
 *         texBuf.setData(tex_coord_list); // you can free the lists after this
 *
 *         vBuf.enable();
 *         texBuf.enable();
 *
 *         r->getExt()->glDrawArraysEXT(GL_TRIANGLES, 0, nVertices);
 *
 *         vBuf.disable();
 *         texBuf.disable();
 *
 *      The data is always assumed to be interleaved (xyzxyz...)
 *
 *   2. Pixel buffers are used to write and rewrite pixel data to a GL structure
 *      (normally a texture). In this case, there use is slighly different.
 *      Instead of passing the image data directly to glTexImage...(), you
 *      pass NULL and instead enable the pixel buffer first. Ex:
 *
 *         RE_OGLPixelWriteBuffer pBuf(xres, yres);
 *
 *         pBuf.setFormat(RE_GPU_UINT8, 4);
 *         pBuf.setData( image_data );
 *         pBuf.enable();
 *         glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, xres, yres, 0,
 *                      GL_UNSIGNED_BYTE, GL_RGBA, NULL);
 *         pBuf.disable();
 *
 *      After that, you can change the texture (or a portion of the texture)
 *      by calling setData() again.
 *
 *      You can also use a pixel buffer as a target for reading data back from
 *      the GPU (via glReadPixels(), glGetTexImage(), etc).
 *
 *         RE_OGLPixelReadBuffer pBuf(xres, yres);
 *
 *         pBuf.enable();
 *         glReadPixels(0,0, xres, yres, GL_RGB, GL_UNSIGNED_BYTE, NULL);
 *         pBuf.disable();
 *
 *         ptr = pBug.getData();
 *
 *      This allows you to do asynchronous reads. The glReadPixels() starts the
 *      DMA transfer, but does not wait - the getData() does.
 *
 *   Finally, the various types of buffer objects, and their default settings,
 *   are:
 *
 *   Vertex:
 *      RE_OGLVertexBuffer       vertex position        3 fp32
 *      RE_OGLColorBuffer        vertex color           3 fp32
 *      RE_OGLNormalBuffer       vertex normal          3 fp32
 *      RE_OGLTexCoordBuffer     vertex texture coords  2 fp32
 *
 *   Pixel:
 *      RE_OGLPixelReadBuffer    read pixels from GPU   3 uint8
 *      RE_OGLPixelWriteBuffer   vertex position        3 uint8
 */
#ifndef RE_OGLBufferObject_H
#define RE_OGLBufferObject_H

#include "RE_API.h"
#include "RE_Types.h"

class RE_Render;

class RE_API RE_OGLBufferObject
{
public:
    // Alternatively, you can use the convenience classes listed below.
    enum RE_BufferObjectType
    {
        VERTEX,
        NORMAL,
        COLOR,
        TEXTURE_COORD,
        ELEMENT,
        
        PIXEL_WRITE,
        PIXEL_READ
    };

             RE_OGLBufferObject(RE_BufferObjectType type, int num_elements);
    virtual ~RE_OGLBufferObject();

    enum RE_UsageHint
    {
        // passing data to GPU only.
        WRITE_ONCE,   
        WRITE_FREQUENT,
        WRITE_STREAM,           // once per redraw.

        // reading data from GPU only.
        READ_ONCE,
        READ_FREQUENT,
        READ_STREAM,

        // read and write (ex: rendering to a vertex list to use as geo)
        READ_WRITE_ONCE,
        READ_WRITE_FREQUENT,
        READ_WRITE_STREAM
    };

    // 1. Set up the buffer data type and number of elements in the buffer.
    //    Matrix types are not supported.
    //    'elements' is the number of data types in the buffer, not bytes (so
    //    for a list of 20 fp32 vec3's, pass 20, not 60 or 240). 
    
    void        setFormat(RE_GPUType type, int vectorsize);
    void        setNumElements(int numelems);

    // You can optionally give GL a hint how you'll be using the data.
    // Hints are set reasonably for the convenience classes below. This also
    // affects the read/write status of mapData(). 
    void        setUsage(RE_UsageHint hint);

    // 2. Fill in the data
    //    if sublen == 0, the full size is used. Otherwise, you can update
    //    portions of the array. Passing NULL frees the buffer.
    void        setData(RE_Render *r, const void *data,
                        int offset = 0, int sublen = 0);

    // 3. Enable the buffer for use
    //    (all NULL data pointers for the appropriate type refer to this buffer)
    virtual void enable(RE_Render *r);

    // 4. Disable the buffer once you're done drawing.
    virtual void disable(RE_Render *r);


    //  If you want to write or read directly from the memory chunk,
    //  this returns a pointer to the data. You must upmap it when you're done.
    //    Do NOT delete this pointer - it is owned by the graphics driver.
    void       *mapData(RE_Render *r);
    void        unmapData(RE_Render *r);

    // This is a convenience method that will draw the object with all
    // currently enabled buffer objects (you only need to call this on one of
    // the buffers, if multiple buffers are enabled). 'gltype' is the GL
    // primitive you want to draw (GL_LINES, GL_TRIANGLE_STRIP, GL_QUADS, etc)
    void        drawObject(RE_Render *r, int gltype);

    // This is a convenience method that will draw objects using randomly
    // selected elements from the array.
    void        drawElements(RE_Render *r, int gltype,
                             int num, const unsigned int *elements);

    static bool hasVertexBufferSupport(RE_Render *r);
    static bool hasPixelBufferSupport(RE_Render *r);
    
private:
    RE_BufferObjectType myObjectType;
    GLenum              myDataType;
    int                 myVectorSize;
    int                 myNumElements;
    GLenum              myStreamType;
    GLuint              myBufferID;
    GLenum              myBufferType;
    bool                myBoundFlag;
    bool                myEnableFlag;
};


// A vertex buffer stores the positions for a vertex list.
// Data type defaults to 3 32bit floats.
class RE_API RE_OGLVertexBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLVertexBuffer(int num_vertex = 0)
        : RE_OGLBufferObject(VERTEX, num_vertex)
    {}
};

// A color buffer stores the vertex colors for a vertex list.
// Data type defaults to 3 32bit floats.
class RE_API RE_OGLColorBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLColorBuffer(int num_vertex = 0)
        : RE_OGLBufferObject(COLOR, num_vertex)
    {}
};

// A normal buffer stores the vertex normals for a vertex list.
// Data type defaults to 3 32bit floats.
class RE_API RE_OGLNormalBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLNormalBuffer(int num_vertex = 0)
        : RE_OGLBufferObject(NORMAL, num_vertex)
    {}
};

// A normal buffer stores the vertex normals for a vertex list.
// Data type defaults to 2 32bit floats.
class RE_API RE_OGLTexCoordBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLTexCoordBuffer(int num_vertex = 0, int multitexture_level = 0)
        : RE_OGLBufferObject(TEXTURE_COORD, num_vertex),
          myMultiTextureLevel(multitexture_level)
    {
        setFormat(RE_GPU_FLOAT32, 2);
    }
    
    virtual void enable(RE_Render *r);
    virtual void disable(RE_Render *r);
    
private:
    int myMultiTextureLevel;
};


class RE_API RE_OGLElementBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLElementBuffer(int num = 0)
        : RE_OGLBufferObject(ELEMENT, num)
    {
        setFormat(RE_GPU_UINT32, 1);
    }
};



// A pixel read buffer is used to read data back from the GPU.
// Data type defaults to 3 8bit ints.
class RE_API RE_OGLPixelReadBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLPixelReadBuffer(int xres = 0, int yres = 1)
        : RE_OGLBufferObject(PIXEL_READ, xres * yres)
    {
        setFormat(RE_GPU_UINT8, 4);
        setUsage(READ_ONCE);
    }
};

// A pixel write buffer is used to write data to the GPU.
// Data type defaults to 3 8bit ints.
class RE_API RE_OGLPixelWriteBuffer : public RE_OGLBufferObject
{
public:
    RE_OGLPixelWriteBuffer(int xres = 0, int yres = 1)
        : RE_OGLBufferObject(PIXEL_WRITE, xres * yres)
    {
        setFormat(RE_GPU_UINT8, 4);
    }
};

#endif

---