Using Libraries

This is an excerpt from an article published in QBXL Magazine, with 
permission by SJ Zero, the author.

FreeBASIC's greatest strength is it's ability to seamlessly integrate with 
a number of standard C libraries while maintaining the ease of use that is 
QB. Even before FB had a built-in graphics library, intrepid coders were 
using SDL to get graphics and sound routines working. Before the current 
version included a SDL_net and Winsock, a number of coders, myself 
included, fought with the headers to get network support into FreeBASIC. 
Today, I'm just going to cover how to get started with three advanced 
libraries: SDL, fmod, and tinyPTC. After understanding the fundamentals, 
you'll see that using C libraries is simple enough that with few 
exceptions, C libraries are no more difficult to use in FreeBASIC than QB 
libraries were to use.

 What are these Libraries, Anyway? 

These libraries are particularly useful because they tend to provide 
functions for games. 

SDL is a library with graphics and input support built in, and a bunch of 
sub-libraries for network, TrueType font support, and audio. It can be used 
with OpenGL, but I won't be covering that today.

TinyPTC is primarily a graphics library, the simplest one available. It 
does little more than give you a pointer to the graphics region to draw to.

FMod is a 3d sound and music library. Though its license is strange, it 
works acceptably for playing sounds, and it nicely encapsulates 3D sound.

 Including the Library 

The first step in getting any of these libraries to work is including their 
header files in your project.
For SDL, it's simply

    #include "SDL\SDL.bi"

For FMOD, it's 

    #include "fmod.bi"

and for tinyPTC, you'll want

    #include "tinyptc.bi"

'2. Initilizing the library, loading a file'

Obviously, you can't just include the lib and fire away if it's got to do 
stuff first. 
To initilize SDL and load a bitmap into memory, you must:

   Const SCR_WIDTH = 640
   Const SCR_HEIGHT = 480
   Dim MenuScreen As SDL_Surface Ptr 'our bitmap
   Dim Shared video As SDL_Surface Ptr 'our screen surface

   SDL_Init ( SDL_INIT_VIDEO )
   video = SDL_SetVideoMode( SCR_WIDTH, SCR_HEIGHT, 32, 0 ) 'sets the video mode for 640x480x32
   MenuScreen = SDL_LoadBMP("bitmap.bmp")

To initilize FMOD and load a sound into memory, you must: 

   Dim sound As Integer 'it's just a handle, so it's an int!

   If FSOUND_GetVersion <= FMOD_VERSION Then
   ErrorQuit "FMOD version " + Str$(FMOD_VERSION) + " or greater required"
   End If

   If FSOUND_Init(44100, 32, 0) = False Then
   ErrorQuit "Can't initialize FMOD"
   End If

   sound = FSOUND_Sample_Load(FSOUND_FREE,"sound.wav", FSOUND_HW3D, 0, 0)

Finally, there's no data formats to load with tinyPTC because it's so 
simple, but you initilize it by going:

   Const SCR_WIDTH = 320
   Const SCR_HEIGHT = 200
   Const SCR_SIZE = SCR_WIDTH*SCR_HEIGHT

   If( ptc_open( "tinyPTC test", SCR_WIDTH, SCR_HEIGHT ) = 0 ) Then
   End -1
   End If

 Blitting, Playing, or Plotting 

The most important step, obviously, is to get whatever you want to do to 
the screen or speakers. This part is relatively easy, and can be 
encapsulated further into a wrapper function. For SDL, sending an image to 
the screen means going:


   Sub BlitImage(x As Integer,y As Integer,image As sdl_surface Ptr, dest As sdl_surface Ptr) 
   Dim Rectangle As SDL_Rect 
   Dim Rectangle2 As SDL_Rect 


   Rectangle.X = 0 
   Rectangle.Y = 0 
   rectangle.w = image->w 
   rectangle.h = image->h 
   Rectangle2.x = x 
   Rectangle2.y = y 

   SDL_BlitSurface image, @rectangle, dest, @rectangle2

   End Sub

For FMOD, the steps to play a sound aren't that difficult either:

   Function fModPlayWave( samp1 As Integer ) As Integer 
   'where samp1 is the number returned by FSOUND_SampleLoad

   Dim position(0 To 2)' as FSound_Vector
   Dim vel(0 To 2)' FSound_Vector


   fModPlayWave = FSOUND_PlaySoundEx(FSOUND_FREE, samp1, NULL, True)

   End Function

And TinyPTC, which is again, not a high level library like the other two, 
can plot pixels using the following code:

   Sub putd(ByRef buffer(), ByVal x As Integer, ByVal y As Integer, ByVal colr As Integer)
   		buffer((y * SCR_WIDTH) + x) = colr
   		ptc_update @buffer(0) 'This is a pageFlip
   End Sub

 Shutting Down 
So you don't have to manage memory and do all the boring mundane tasks, you 
must remember to shut down the library before your program exits. Luckily, 
all three programs allow this with one line. If you can't shut it down, the 
library no longer cares. It's beautiful.


   SDL: SDL_Quit ()


   fmod: FSOUND_Close ()


   tinyPTC: PTC_Close ()

That's all there is to quitting!
As you can see, there is nothing inherently more difficult in using 
libraries in FreeBASIC compared to QuickBASIC. In fact, because coders 
don't need to jump through hoops to get to memory, it's actually much 
easier, even with the more modern OS and hardware.

Last Reviewed by Sancho3 on February 06, 2018
