Qoob: Tiny 3d modeller and Library

What is Qoob?

Qoob is a library of 3d commands that can be used to create or load 3d models. The models are designed to be as tiny as possible as is the qoob library.

Why is qoob special?

Size. The library (just 2kilobytes) and models (just a few bytes) are tiny.In fact I believe that no mesh compression could beat qoob model size for the same models. Qoob models may contain thousands of polygons but be stored in a few tens of bytes. Qoob turns out to be topology sensitive. The more "limbs" or "details" a model has, the more bytes are needed to store. This is, in some way, optimal.

How are models created?

Qoob library comes with a modeller Qoob Modeller that produces models in a special format with a .qob extension. These .qob models can be loaded by any program including the qoob library which expands them into meshes ready for rendering. Qoob modeller is similar to wings3d in design but with less functionality to keep the size down. All models in qoob are built from a cube - hence the name.

How small is Qoob?

The qoob library compressed using crinkler 1.1 is 2165 bytes (version 1.0.1) and thus it can be used in programs targetting 8k-64k

How small are .qob models?

.qob models are typically less than a hundred bytes, some are smaller than 10 bytes and some are as "big" as 350 bytes

What sort of meshes does qoob use?

Qoob is a genus-0 , quad mesh. There are good reasons for this including size, subdivision and the fact that quads make more natural surfaces.

How fast is qoob?

Qoob is moderately fast. Most models can be loaded and converted to meshes ready for display in less than a second. The slowest function is the catmull clarke subdivision and smooth. Once the model becomes ten thousand or more polygons this can take several seconds to work. This may be fixed in the future but it will cost more bytes. 

So Qoob is a cool tiny lib and a Modeller - why not use a commercial modeller?

Yeah that would be great. No work for me on the modeller and artists could use a commercial grade tool. The problems are many though. Briefly, the modellers functions are not one to one with qoob (eg catmull clark gives different results in different modellers and not the same as qoob). Not all functions are available anyway. Compression is done on the fly in qoob and so wysiwyg (barring bugs) also not true if we use commercial modellers. This means you model something, export and load it and it WILL be different. Not too useful.

Qoob sounds great - whats the catch?

Qoob library is limited in scope and functionality. Qoob modeller therefore misses many common modelling commands (eg moving vertices). Qoob modeller is not a fully featured modeller aimed at replacing Wings3d or Zbrush etc. It is designed for purpose, to create tiny models. One side effect of this is targetting specific models is sometimes hard whereas creating something interesting and tiny is very easy.

Qoob loads .qob models but can it be used as a library without them?

Yes, qoob library can create models programatically, not just load .qob ones. In essence every qoob library command takes a mesh and returns a mesh. This mesh is very simple. You are able to add you own functions easily. This means it would be possible to manipulate a .qob model in any way or start with an empty model and create anything. Trees, menger sponge, ribbons, extrusions - anything.

Does qoob use any third party libraries?

Qoob modeller uses glut for windows (yes, I know, ancient stuff ;-) and some Microsoft libraries for dialog boxes. Glut for windows license allows free distribution so there are no license issues.
Qoob library (for OpenGL) that you use in the final program does not use any third party libraries.

What does Qoob library consist of?

There are four main parts:
  1. A maths library
  2. Modelling commands library such as extrude, smooth etc
  3. Selection control (eg pick this polygon, pick similar polygons)
  4. Loading and saving support
It is written in C and does not use external libraries of any kind.

Is .qob an open format? Can I write my own loader?

Yes and no. Yes it can be opened up for you but no, it will not help. The .qob format stores modelling commands, not meshes. This decreases the amount of data needed to store models. This means the .qob format is essentially a series of calls into the qoob library to do exactly what the modeller did. Thus the .qob format is useless without the qoob library. However the mesh format that the qoob library produces is open.

Is Qoob open source?

No. However binaries/modeller are now available for download.

Is Qoob free?

Yes (as in beer), except for commercial use where a small fee may be charged.

Does qoob work for 256 bytes, 1k or 4k intros?

Currently Qoob (1.0.2) does not. Although it is very small, it is primarily aimed at 8k-64k. Qoob lib is 2.1k, models around 100 bytes (on average) then you need a world and camera.

Does qoob support textures/normal maps/animation/skinning/colours?

No it does not. Qoob 1.0.2 is targetted at basic 3d models only (meshes). However qoob supports both face and vertex normals for lighting purposes. Imagine qoob as a simply a mesh editor.

How do I render the models?

You need to write your own rendering functions - rendering is not part of qoob. However, meshes are designed to be easy to use modern rendering techniques such as vertex arrays easily. Code for such a function in OpenGL is below.

Is qoob an OpenGL or DirectX tool.

Both. Qoob does not draw anything and is self contained. Though the modeller is written in opengl, the qoob lib and .qob models do not care and can be used by either library. Equally, qoob can be used in an embedded envrionment with OpenGL-ES.

What technologies do you use?

Qoob is written in C and does not use any libraries (not even stdlib!). The Qoob modeller uses GLUT and OpenGL. Qoob compiles under VC++2008 and 2010 (as far as I know). The qoob modeller runs under windows. If anyone wishes to port to GCC/linux let me know. Importantly qoob must be compressed to achieve such small sizes. The current compressor used is crinkler 1.1, however other compressors could be used but at this size of library crinkler is the best of breed.

Have you made intros with it?

Yes, I hate people who launch libraries they haven't used too. I did make some test intros (without music) with it and this helped reduce load time and tackled performance problems. However, there are no released intros yet.

How do I load a .qob model into an intro?

You dont. .qob is for the modeller. You export as C code to a .h then , say, rename this to model.h.
Now in your C code:
#include "qoob.h"
#include "model.h"
Object mymesh;

unpack (&qobj0, &mymesh);

The first parameter is the qoob object in the .h file. You can of course rename it by hand to anything you like. Eventually I'll get around to do this from the qoob modeller to make it easier.

How do I render the qoob mesh format in OpenGL?

Assuming you have unpacked it like above, here is example OpenGL code to render the mesh format that is assumed by qoob lib:

void drawObject (Object *ob, uint style, uint normon) {
    glEnableClientState (GL_VERTEX_ARRAY);
    glVertexPointer        (3, GL_FLOAT, 0 , (GLvoid*)&(ob->v[0]) );
    // vertex normals assumed here
    glEnableClientState  ( GL_NORMAL_ARRAY );
    glNormalPointer        ( GL_FLOAT, 0 , (GLvoid*)&(ob->n[0]) );
    glDrawElements       ( style, ob->nq*4, GL_UNSIGNED_INT, (GLvoid*)&(ob->q[0]) );
    glDisableClientState ( GL_NORMAL_ARRAY );
    glDisableClientState ( GL_VERTEX_ARRAY );

Adaptive Subdivision?

It would be very useful. The code is bigger. I decided not to do so yet.

Whats your roadmap?

Qoob version 2.0 is planned which will target 64k intros and include some functions never seen at this size before. Its mostly under wraps. Qoob modeller will be expanded to cope with these new functions. It means qoob will produce models previously impossible at this size. In addition animation support will be added.
It is likely a camera path and world editor will be added and paths will be very compact,.
It is likely a 4k version will be made with reduced functionality, targeting directX only.
Qoobfx library is underway. This is a realtime library to be used with qoob. It aims to be fast and small and includes advanced features like mesh breaking, ambient occlusion, joining meshes, fractalising meshes, laplacian smooth and so forth. Qoobfx will be dynamically loaded and so only functions used will affect the final exe size.

Timescales are to be discovered.