BrBegin must be called before most BRender functions can be used. BrEnd frees internal resources and memory. These will normally be the first and last function calls in your BRender programs.
BrBegin();
/*
* Initialise screen buffer and set up CLUT (ignored in true colour)
*/
screen_buffer = DOSGfxBegin(NULL);
palette = BrPixelmapLoad("std.pal");
if(palette)
DOSGfxPaletteSet(palette);
/*
* Initialise Z-Buffer renderer
*/
BrZbBegin(screen_buffer->type,BR_PMT_DEPTH_16);
. . .
. . .
. . .
. . .
. . .
. . .
BrZbEnd();
DOSGfxEnd();
BrEnd();
BRTUTOR1.C
/*
* Program to Display a Revolving Illuminated Cube
*/
#include <stddef.h>
#include <stdio.h>
#include "brender.h"
#include "dosio.h"
int main(int argc, char **argv)
{
/*
* Need screen and back buffers for double-buffering, a Z-Buffer to store current
* depth information, and a storage buffer for the currently loaded palette
*/
br_pixelmap *screen_buffer, *back_buffer, *depth_buffer, *palette;
/*
* The actors in the world: Need a root actor, a camera actor, a light actor,
* and a model actor
*/
br_actor *world, *observer, *light, *cube;
int i; /*counter*/
/********** Initialise BRender and Graphics Hardware ****************/
/*
* Start BRender
*/
BrBegin();
/*
* Initialise screen buffer and set up CLUT (ignored in true colour)
*/
. . .
. . .
. . .
. . .
. . .
. . .
/*
* Initialise Z-Buffer renderer
*/
BrZbBegin(screen_buffer->type, BR_PMT_DEPTH_16);
/*
* Allocate back buffer and depth buffer
*/
back_buffer = BrPixelmapMatch(screen_buffer,BR_PMMATCH_OFFSCREEN);
depth_buffer = BrPixelmapMatch(screen_buffer,BR_PMMATCH_DEPTH_16);
/*************** Build the World Database **********************/
/*
* Start with None actor at root of actor tree and call it `world'
*/
world = BrActorAllocate(BR_ACTOR_NONE,NULL);
/*
* Add a camera actor as a child of None actor `World'
*/
observer = BrActorAdd(world,BrActorAllocate(BR_ACTOR_CAMERA,NULL));
/*
* Add, and enable, the default light source
*/
light = BrActorAdd(world,BrActorAllocate(BR_ACTOR_LIGHT,NULL));
BrLightEnable(light);
/*
* Move camera 5 units along +z axis so model becomes visible
*/
observer->t.type = BR_TRANSFORM_MATRIX34;
BrMatrix34Translate(&observer->t.t.mat,BR_SCALAR(0.0),BR_SCALAR(0.0),
BR_SCALAR(5.0));
/*
* Add a model actor: The default unit cube
*/
cube = BrActorAdd(world,BrActorAllocate(BR_ACTOR_MODEL,NULL));
/*
* Rotate cube to enhance visibility
*/
cube->t.type = BR_TRANSFORM_MATRIX34;
BrMatrix34RotateY(&cube->t.t.mat,BR_ANGLE_DEG(30));
/***************************** Animation Loop ******************************
/*
* Rotate cube around the x-axis
*/
for(i=0; i < 360; i++) {
/*
* Initialise depth buffer and set background colour to black
*/
BrPixelmapFill(back_buffer,0);
BrPixelmapFill(depth_buffer,0xFFFFFFFF);
/*
* Render scene
*/
BrZbSceneRender(world,observer,back_buffer,depth_buffer);
BrPixelmapDoubleBuffer(screen_buffer,back_buffer);
/*
* Rotate cube
*/
BrMatrix34PostRotateX(&cube->t.t.mat,BR_ANGLE_DEG(2.0));
}
/* Close down */
BrPixelmapFree(depth_buffer);
BrPixelmapFree(back_buffer);
BrZbEnd();
. . .
. . .
. . .
. . .
. . .
. . .
BrEnd();
return 0;
}
BRTutor1.c
Platform specific code, omitted from the program listings in this tutorial, is required to initialise display hardware, colour buffers and palettes. Sample hardware initialisation code is included in the program listings at the back of your platform-specific installation guide, and in the sample programs on your Tutorial Programs disk. In general, this sample code contains generic examples of how screen handling operations may be implemented on your platform. You may decide to optimize this code for your own purposes, or substitute your own screen handling and I/O routines.
The sample initialisation code listed above illustrates how a DOSbased application might initialise the graphics hardware. This code is discussed below, for illustrative purposes. If you are not running BRender x86 under DOS, refer to your installation guide and to the sample program listings on your Tutorial Programs disk.
A number of screen handling functions are provided for use with DOSbased BRender applications. These functions are provided to simplify graphics hardware initialisation and are documented in the BRender x86 Installation Guide.
DosGfxBegin and DosGfxEnd are used to initialise the graphics hardware.
DOSGfxBegin expects a character string argument in the following format:
VESA/MCGA, [W:<width>],[H:<height>],[B:<bits/pixel>]The default string
MCGA,W:320,H:200,B:8 is assumed if NULL is passed as an argument to DOSGfxBegin (and the BRENDER_DOS_GFX environment variable has not been set). BRender x86 v1.2 supports 15- and 24-bit true colour, as well as 8-bit indexed colour.
If you don't know which graphics screen modes are supported by your system, run VESAQ.EXE, BRender's hardware interrogation utility for DOS based systems. This utility, located in the Tools directory, interrogates your video circuitry before displaying a list of the video modes supported by your system.
If NULL is passed as an argument to DOSGfxBegin, the screen mode can be altered after compilation by setting the BRENDER_DOS_GFX environment variable. For example, type:
SET BRENDER_DOS_GFX=VESA,W:640,H:400,B:8followed by Return to select the 640 400, 8-bit VESA standard (assuming your video card supports this mode). Now run
BRTUTOR1.C again. Notice that the program runs much slower at this higher screen resolution and that the quality of the image has improved (the `staircase' effect at the edges of the cube is not as pronounced). Real-time rendering always involves a trade-off between image quality and speed. To revert to the original screen mode in DOS type:
SET BRENDER_DOS_GFX=MCGA,W:320,H:200,B:8followed by Return. Experiment with the screen modes available to you. In general, the lower the resolution the faster your animation will run. You may specify simply MCGA or VESA and BRender will select appropriate arguments for
W, H and B.
DOSGfxBegin returns a pointer to a pixel map that references the screen. This pointer is assigned here to screen_buffer. This pixel map could be a hardware screen buffer mapped directly to the screen or a pixel map set up by BRender to simulate a hardware screen buffer. Either way, from the application programmer's point of view, the contents of this buffer are displayed on screen.
When rendering in 8-bit indexed colour mode, a colour palette must be loaded into the hardware palette (or CLUT). BrPixelmapLoad loads a pixel map from a specified file into memory. DOSfxPaletteSet copies the contents of a pixel map to the hardware palette. The initialisation code listed above loads the colour palette supplied with BRender, std.pal, into memory, then copies it to the hardware palette.
BrZbBegin is used to select and initialise the Z-Buffer renderer. BrZbEnd closes it down. Remember that a BRender scene description is designed to be independent of a particular rendering environment. This means that porting a BRender program between platforms that support different rendering engines can be accomplished by changing a couple of lines of code - in this case BrZbBegin and BrZbEnd. Refer to your installation guide for details of the rendering options available.
The renderer needs to know the `type' of buffer it will be rendering into - whether it contains indexed or true colour information and the number of bits per pixel. It also needs to know the depth of the Z-Buffer. This information is passed to BrZbBegin.
BRTUTOR1.C contains additional initialisation code shown in the program extract below.
BrBegin();
screen_buffer = DOSGfxBegin(NULL);
palette = BrPixelmapLoad("std.pal");
if(palette)
DOSGfxPaletteSet(palette);
BrZbBegin(screen_buffer->type,BR_PMT_DEPTH_16);
/*
* Allocate back buffer and depth buffer
*/
back_buffer = BrPixelmapMatch(screen_buffer,BR_PMMATCH_OFFSCREEN);
depth_buffer = BrPixelmapMatch(screen_buffer,BR_PMMATCH_DEPTH_16);
. . .
. . .
. . .
. . .
. . .
. . .
BrZbEnd();
DOSGfxEnd();
BrEnd();
Before initialisation is complete, we must create a back buffer in the image of the screen buffer to facilitate double-buffering. Since we're using the Z-Buffer renderer, we also need a depth buffer of the same width and height. BrPixelmapMatch takes care of this. BR_PIXELMAP_OFFSCREEN tells it to replicate the screen buffer. BR_PMMATCH_DEPTH_16 tells it to create a 16-bit depth, or Z-, buffer, of the same width and height as the screen buffer. The initialisation procedure introduced above could be used as a general purpose template for initialising BRender programs. You may well find yourself writing many BRender programs without making significant alterations to this sequence of function calls. Indeed, you are unlikely to alter any of this code unless you are selecting a different renderer or changing the graphics screen mode. Take time to familiarise yourself with the function calls and data structures introduced above. They are the foundations upon which your conceptual model of BRender will be built.