Skip to content

Tutorial: basics

Jump to bottom Edit New page
theZiz edited this page May 12, 2013 · 20 revisions

Welcome to the first basic Tutorial of sparrow3d. In this text I will explain, what the principle behind sparrow is, what it is useful for (and what not for), and why most things are as they are. However to look up a specific function look in the documentation located here: http://ziz.openhandhelds.org/documentation.

Table of Contents

Introduction

Sparrow3d first started 2010. At this time it did not have this name. In fact it wasn't a library at all, just a couple of functions used in my project "snowman". I created some functions for the main loop and other stuff and especially I wrote a 3D software renderer. The big goal was to write these functions once - with many #defines for different systems - and then just use them and don't have to mind the system I want to compile for. Later with Puzzletube and Schwerkraft I decided to split it and to give it a cool name: Sparrow3D was born.

The Sparrow3d "policy"

It started with some main loop, software rendering and event management functions, but now sparrow3d is a framework for many things needed in game development.

I thought about some kind of policy for Sparrow3d. If I write new code and have to make decisions, whether I do things in some or another way, I use this policy.

  • First of all: sparrow3d is free software and will always be. I use a lot of free software, so it is just fair to give something back
  • sparrow3d is 100% compatible to SDL and other SDL libs (e.g. SDL_image). You can mix SDL and sparrow3d code whenever you want. You can add sparrow3d to an existing SDL application or using SDL features in sparrow3d, which are not encapsulated. Of course you have to mind some things sometime, e.g. sparrow3d uses a zBuffer. If you ignore it, the result may be unexpected. But more about this later. ;-)
  • pure C. sparrow3d don't use OOP. I think for such an easy framework it is clever to choose the same way like SDL or OpenGL. But of course you can use OOP in your applications and encapsulate sparrow3d calls.
  • compatibility between (sometimes very) different handhelds: sparrow3d is (at the moment) available for GP2X (F100 and F200, old firmware and open2x), Wiz, Caanoo, Dingux, Open Pandora, GCW Zero, PC Linux and PC Windows. Furthermore people compiled it for S60 (Symbian) and Meego, too, in the past. However I do not support this ports, but you can see, how easily you can port it to another platform. Buildung for PC (Linux and Windows) is very important for testing and debugging. The handhelds have most of the times different display resolutions or different kinds of (or no) touchscreens and always different inputs. So for most cases I use the principle of the least common denominator, which is the GP2X. That means:
    • All internal surfaces are 16 bit surfaces. If you want to use more than 16 bit you have to use tricky workarounds or native SDL calls (which will be slower - there is a reason I use 16 bit). A surface is some kind of an image object in SDL.
    • No alpha channel. Sparrow3d only supports an alpha color, which will be ignored if enabled. If you want to blend smooth alpha you have only a few (slower) functions, which I explain later.
    • Touchscreen, but no pressure sensivity. Furthermore the "cursor" doesn't move as you would expect from moving the mouse under Linux and Windows. Because on a touchscreen you can ONLY move the cursor if you touch the screen (or click in Windows/Linux). So there is no movement update when the mouse/touchscreen is not pressed.
    • no 3D hardware acceleration: If you want fast mid or high poly graphic, you have to use opengl es with sparrow3D, which should be possible because of SDL, but however does it really make sense? It would destroy the basic idea of sparrow3d of compiling a game for nearly every platform. However the software renderer is a relatively fast renderer, that runs everywhere, but is still software.
    • The nubs of the pandora are not handled as extra controls. The generic input device has exactly two axis, which you can read as digital or analog input. However the nubs and the d-pad are mapped to the same input. If a device doesn't have real analog input axis, they are emulated.
    • Of course the screen resolution is NOT limited... But one reason I made this 3d software renderer WAS to easily have the same objects on different screen resolutions :)
If you want to add some code to sparrow3d - and I would enjoy to see your commits -, please try to not break this policy. It is a shame that there are so many different handhelds out there, every one with its own standards and its own programs. I want to unite them in the darkne... Nevermind. I want to make a framework for every handheld, where everybody can easily compile for systems he doesn't even OWN!

Oh and something about the name: I don't care about how you spell it: sparrow3d, Sparrow3d, sparrow3D, Sparrow3D, SpÄrr0w3d - I don't mind, I even mix it, too.

Features

This is just a small overview of the features of sparrow3d. You can only know all feature if you read the whole documentation. ;-) But here are some things, that really should mentioned. I divided them like the parts of sparrow3d. More about the fragmentation you will read in the Core Tutorial.

Core

  • Window creating
  • Double Buffer drawing
  • Event handling
    • Abstract controller model, which is same for every handheld
    • Touchscreen support as part of the generic input device
    • Window resize event handling
    • Easy mainloop function
  • Creating or Loading fast and screen compatible surfaces
  • Surface Caching

Math

  • fast functions for fixed point numbers
    • most open handhelds do not own an FPU, which means, that floating point operations are really slow. Fixed point numbers are a bit tricky, but MUCH faster
  • Lookuptables for fixed point versions of
    • Sin, Cos, Tan
    • Asin, Acos
    • Square root
    • Min and Max function

Primitives

  • Drawing on different render targets, e.g. the screen or any other surface
  • z-Buffer for the render target for z-testing and z-setting
    • easy method for sorting your stuff
    • very imported for the 3D part of sparrow3D
    • z-set and z-test are configurable one at a time
    • all drawing functions in sparrowPrimitives uses the z-Buffer (optional)
  • Alpha Test (optional)
  • Pattern Text (optional), e.g. for dithering or alpha blending emulation
  • very fast solid color triangle and quad function
  • fast textured triangle and quad function
  • very fast blitting of surfaces or parts of them (blit is drawing without zoom or rotation)
  • fast rotozoom (faster than SDL_gfx) draw of surfaces or parts of them (rotozoom means drawing with rotation and zoom)
  • very fast solid color rectangle and ellipse function
  • fast solid color rectangle and ellipse border function
  • fast line

Renderer

If you don't get some points, don't mind: I'll explain later. ;-)

  • Based on matrices (like openGL)
    • Functions for setting up the projection matrix
    • Functions for setting up the model view matrix like Scale, Translation and Rotation
  • up to 8 lights
  • 3D triangles and quads with and without textures
  • drawing meshs (a couple of 3D triangles and quads. Faster than drawing them yourself)
  • 3D lines, rectangles, ellipse and rectangle and ellipse borders
  • 3D blit surface
  • optional perspectively correct drawing based on square root lookup table

Mesh

  • Loading Meshes from obj wave files

Sprite

  • easy and fast sprite engine
  • support of tiling
  • fast rotozoom (faster than SDL_gfx)
  • drawing in 3D space
  • loading sprites from file

Font

  • Creating lookup tables for different fonts and font sizes
  • Very fast caching for very fast font drawing
  • Borders for loaded fonts
  • Drawing text on the screen with left, center and right alignment
  • Some blending possibilities for better reading
  • full unicode plane 0 (first 65535 utf8 signs) support

Text

  • easy to use system to seperate program and different translations
  • loading or ingame creating of text<->translations bundles
  • management of different bundles of texts (on their part with different translations) for diffrent parts of your game, like menu-texts (which you need everytime) and level-texts, which change every new level

File

  • platform independent file functions
  • Reading lines from files
  • Searching for files in folders (recursive)
  • Creating folders
  • Deleting folder/files

Sound

  • Encapsulation for SDL_Mixer for easier and more error prove sound functions
  • optional, because a stand-alone library
Furthermore there are seven example applications.

To Do

  • network (based on SDL_net)
  • maybe an easy GUI
  • ponies would make sparrow3D 20% cooler...

Conclusion

I hope now you have a LITTLE understanding, what sparrow3d is usefull to - and what not. In the next chapters you will get detailed knowledge about every functions of sparrow3d starting with the Core functionalities.

Enjoy! Ziz

Add a custom footer
Add a custom sidebar
Clone this wiki locally