Wrapper Library for Irrlicht

Introduction

Overview

The first thing I must do is acknowledge the fantastic work that has been carried out by the many different authors whos amazing work makes it possible for this package to enable BASIC programmers to build rich and immersive 3D applications and games. You can find a list of acknowledgements at the end of this document.

This wrapper library provides a simple and partial gateway from non object-oriented languages like FreeBasic into the object oriented 3D graphics Engine Irrlicht. Although the wrapper only exposes part of the functionality of Irrlicht it endevours to expose the most important parts to give you access to Irrlichts powerful features. It does not directly expose the Irrlicht commands but provides a seperate syntax to encapsulate the engine.

In total it provides well over 200 commands that cover Bitmaps, 3D models, Maps, Terrains, Cameras, Lights and more. At this time there is no practical support for the Irrlicht GUI, applications would need to provide any widget controls with.

This document serves as an introduction into the wrapper, from here I suggest you follow the installation instructions below and then try out the examples, these practical demonstrations provide an excellent way to learn how the wrapper functions. If you need specific information your first port of call will be the reference manual and your last port of call the IrrlichtWrapper.bi which hopefully you will not need.

Installation

The installation of the IrrlichtWrapper for FreeBasic package is very simple, just extract the zip file to a folder of your choice and your ready to go. You may prefer to move the IrrlichtWrapper.bi file to your FreeBasic\inc directory however I leave it where it is and create my project files within the same directory. As the Irrlicht DLL included with this package is modified to include addition features you cannot use a standard Irrlicht.dll from another download with this package, however if you like to compile your own executables C++ source is provided to enable you to do this.

Note: You will need FreeBasic verion 0.20 or better to use the wrapper

The Scene

When you start Irrlicht with the IrrStart command you create a scene that represents your 3D world, this scene is hidden behind the wrapper and is used to load and store all of your resources: Bitmap Textures, 3D Meshes, Fonts and the Nodes in your world.

The Texture and Image Objects

The texture and the image objects are both 2D bitmaps that are loaded from a bitmap file.

Textures are used to paint the surface of nodes (3D objects) in the scene or can be drawn directly to the screen as an image for counters or logos. Textures are stored in the computers main memory but, where possible, they are also stored in the Graphics Cards video memory to speed up 3D drawing. When you get a new texture the wrapper will return the object to you as an irr_texture type

Images are usualy used as a source of information and are not drawn to the screen and are instead used to set the height of terrains or to describe how grass is distributed. Images are stored only in the computers main memory. When you get a new image file the wrapper will return the object to you as an irr_image.

You need to save and manage both of theses objects so you can use them later. Once you are finished with them it is important that you remove them from memory as images can occupy a lot of memory and you can easily run out of video memory in particular.

The Font Object

An Irrlicht font is a monochromatic bitmap font that can be used to draw simple text onto the display. When you get a new font the wrapper will return the object to you as an irr_font type.

The Mesh Object

The Mesh can be thought of like a blue print and is not actually displayed in your scene. It is a list of triangular geometry that fits together to describe a 3D model, this can be a static prop, a complex map or a character. The mesh can also store animation information and a description of which parts of a texture are to be painted onto its surface.

Where a mesh describes a map it will also have references to dozens of bitmaps that it uses to paint its surfaces.. When you get a new mesh object the wrapper will return it to you as an irr_mesh type.

The Node Object

A node is a physical object in your world a 3D Model, Camera, Light, Terrain, Billboard or Particle System. It is an element that has a position, rotation and scale, it will usually be rendered as a visible element if it is in front of the active camera when the canvas is drawn.

Nodes can usually be painted with a texture a process that is referred to as applying a material, they can be moved, rotated and scaled, hidden from view and deleted from the scene.

A 3D model is usually created by adding a mesh object to the scene. When you create a new node it will be returned to you as an irr_node type.

The Camera Object

A camera object is a special node type and represent your vantage point into the 3D world, the camera has a viewpoint and a target at which it looks. Cameras have a series of special commands that can alter the appearance of the display however they can also be copied directly into variables of type irr_node and be manipulated with all of the node commands. When a camera is created it is returned to you an irr_camera type.

The Terrain Object

A terrain object is a special node type and consists of a large square mesh that is pulled and lowered to represent hills, valleys and mountains. The terrain can be textured to give the appearance of a realistic landmass and with careful design it can even have map objects buried into it. Terrains have some special commands however they can also be copied directly into variables of type irr_node and be manipulated with all of the node commands. When a terrain is created it is returned to you an irr_texture type.

The Particle System Object

A particle system is a special node type that can be set up to spit out hundreds of tiny little Billboard like objects and simulate effects like, fire, explosions, fountains, waterfalls, rain etc ... The particle system has an item called an emitters attached to spit out particles and items called affectors attached to fade then out and change their direction. Particle systems have some special commands however they can also be copied directly into variables of type irr_node and be manipulated with all of the node commands. When a particle system is created it is returned to you an irr_particle_system type.

The Animator Object

Animator objects are attached to nodes and are used to delete, rotate or move the object in some way without you having to control the animation yourself step by step. When you create an animator it will be returned to you as an irr_animator type.

The Selector Object

Selector objects are used to gather together groups of triangular geometry in the scene that can be used for special functions, at the moment the wrapper only supports using them for collision detection. When you create a selector object it will be returned to you as a irr_selector type.

License

The Irrlicht Engine is based in part on the work of the Independent JPEG Group and the zlib. Please refer to the Irrlicht documentation and license agreements for further information.

This software is provided 'as-is', without any express or implied warranty. In no event will the author be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Contact

If you have any problems or suggestions I would be happy to receive them. Although I can not promise any action or an individual response I do try to help where possible and to look after my babies even when I release them into the wild. Mail::frankdodd@ukonline.co.uk

Acknowledgements I wish to express my gratitude to the following people whose work the wrapper is built upon or who have helped with contributions to the wrapper or with technical assistance for various features and problems.
Irrlicht	http://irrlicht.sourceforge.net/author.html
FreeBasic	http://www.freebasic.net/index.php/about?section=credits
Simple Terrain Spattering	With invaluable help from the OpenGL Splat tutorial by Jarno van der Linden (http://www.cs.auckland.ac.nz/~jvan006/multitex/multitex.html)
Grass SceneNode	Released under the Irrlicht License by G Davidson
Clouds SceneNode	Released under the Irrlicht License by G Davidson
Lens Flare Scene Node	Placed into the public domain by Paulo Oliveira
6DOF Camera	With lots of help from Colin MacDonald and theoretical advice from Aleofjax
Color and Spline particle affectors	Released under the Irrlicht License by Dark Kilauea
Newton Physics Engine support	Developed by SiskinEDGE and the library provided by the Newton Game Dynamics team
Open Dynamics Engine Physics support	Bindings developed by D.J Peters and the library provided by the Open Dynamics Engine team.
Many Irrilicht commands and support	Provided by Agamemnus and The Car
FreeType truetype font support	Provided by the FreeType team (www.freetype.org)
Batching Meshes	Provided by Gaz Davidson (Bitplane)
Beam Node	Provided by Gaz Davidson (Bitplane)
Bolt Node	Provided by Sudi and Trivtn under the Irrlicht License
XEffects - Reloaded	Provided by Blindside
Many thanks for the development tools	Code::Blocks (www.codeblocks.org); GCC Compiler (gcc.gnu.org); FBIde (www.freebasic.net); FBEdit (fbedit.freebasic.net); NVu
Lots of thanks for help in the Forums	Eponasoft; Daiwa; Crocodudule, John K, AlecZ, Alvaro Victor; thebignic and everyone that has offered their support. Thanks.
And many thanks to the thousands of mails posts, examples, replies and comments scattered across the Internet that provided insights into many of the questions that needed to be solved in creating this library.