All image formats are derived from 'inc/real/dtype/r3dtype.h' base class. This class defines basic characteristics for two dimensional raster images.

Images consist of Channels such as Color, Alpha and Depth channel. Each of these channels may have number of sub channels. For example, the Color channel defines three sub channels Red, Green and Blue.

The image data may reside on RAM, a file or in video memory, for example.

In order to plug in new image file format, one has to implement the following classes:

Reading Images

If the given file was found, and the format of it was indeed BMP, a bmp object is created.

Then the following methods are called:

All classes derived from 'r3dtype' base class supports row based reading/writing methods.

The following code demonstrates how the system reads a BMP file:

    #include <real/dtype/r3bmp.h>

    R3INT width, height, y;
    R3FLOATCOLOR3 *data;
    
    bmp = R3New(R3CLID_BMP,
                R3DTFA_FileName, "myimage.bmp",
                R3DTFA_Mode, R3DTMODE_READ,
                R3TAG_END);
    R3DoA(bmp, R3DTYPEM_BEGIN, NULL);
    R3GetAttrs(bmp,
               R3DTYPEA_Width, &width,
               R3DTYPEA_Height, &height,
               R3TAG_END);

    data = R3Alloc(sizeof(R3FLOATCOLOR3)*width * height, 0));

    for(y = 0; y < height; y++) 
        R3DoA3(bmp, R3DTYPEM_GETROWFLOAT, (void *)y, (void *)R3DTCHANNELS_RGB, data + y * width );

    R3DoA(bmp, R3DTYPEM_END, NULL);
    R3Dispose(bmp);

Typically R3DTYPEM_BEGIN reads a header of the image file and prepares the object for reading (allocates buffers etc. for reading).

Writing Images

Writing images looks very similar to reading.

The following code demonstrates how Realsoft 3D writes images to a file:

    #include <real/dtype/r3bmp.h>

    R3INT width, height, y;
    R3FLOATCOLOR3 *data;
    
    // allocate and initialize image data
    data = R3Alloc(sizeof(R3FLOATCOLOR3)*width * height, 0));
    ....


    // write image to a file
    bmp = R3New(R3CLID_BMP,
                R3DTFA_FileName, "myimage.bmp",
                R3DTFA_Mode, R3DTMODE_WRITE,
                R3TAG_END);
    R3DoA(bmp, R3DTYPEM_BEGIN, NULL);
    R3SetAttrs(bmp,
               R3DTYPEA_Width, width,
               R3DTYPEA_Height, height,
               R3TAG_END);

    for(y = 0; y < height; y++) 
        R3DoA3(bmp, R3DTYPEM_SETROWFLOAT, (void *)y, (void *)R3DTCHANNELS_RGB, data + y * width );

    R3DoA(bmp, R3DTYPEM_END, NULL);
    R3Dispose(bmp);

Again, image format typically writes header data to a file in R3DTYPEM_BEGIN method. The actual data is written line by line with R3DTYPEM_SETROWFLOAT call.

Type Conversion

Realsoft 3D supports may different data types for reading and writing images. R3DTYPEM_SETROWFLOAT assumes the channel data is given as a scan line of double precision floating point values (64 bit). However, also 1, 8, 16 and 32 bit channels are supported.

Correspondingly, you can read and write image data using any of the following methods:

    R3DTYPEM_SETROWBYTE
    R3DTYPEM_SETROWWORD
    R3DTYPEM_SETROWINTEGER
    R3DTYPEM_SETROWFLOAT
    R3DTYPEM_SETROWRAW

    R3DTYPEM_GETROWBYTE
    R3DTYPEM_GETROWWORD
    R3DTYPEM_GETROWINTEGER
    R3DTYPEM_GETROWFLOAT
    R3DTYPEM_GETROWRAW

The base class takes care of converting the image data to/from the type required by the file format.

Implementing new Image Formats

To plug-in new image format class, such as BMP, JPG or TARGA, call:

    #include <real/dtype/r3imgldr.h>

    R3DoClassA(R3CLID_IMAGELOADER, R3ILCM_REGISTERFILETYPE, (void*)R3CLID_MYFORMAT);

This allows Realsoft 3D to read files of that format automatically.

Implementing Save options

There are two other classes that needs to be implemented in order to allow the program to take full advantage of the file format in question

Examples

See the example plugins in samples/plugins/imageformat folder.