Examples?

[Corey Virgil]

I've looked through all of the SDL documentation that I've found, and it appears that many of the examples are in the form of fragments that don't necessarily make it obvious as to how they fit into the overall scheme of things.  They are more along the lines of "How do I call this function" rather than "How do I accomplish this task."

I think it would be useful to start a collection of small programs that use SDL to do one simple thing.  Play a .wav file, draw a box on the screen, get mouse input, etc...  Of course, these programs would be pretty much useless for anything other than source code examples.  That's fine.

As an example, the below code is a complete program that plays a wav file.  It shows how all the pieces fit together.  However, in order to write it, I had to cull information from (I think) 4 different pages on two separate web sites.

If anyone else thinks that example code in this format would be useful, I'd be happy to whip up some more.

/**********************************************************
           play_wav.c  -  Uses SDL to play a .wav file
***********************************************************/

#include <stdio.h>
#include <stdlib.h>

#include "SDL.h"
#include "SDL_audio.h"
#include "SDL_error.h"

static Uint8 *wav_buffer;
static Uint32 wav_len;
static Uint8 *wav_pos;

int main(int argc, char *argv[])
{
    void fill_audio(void *udata, Uint8 * stream, int len);
    SDL_AudioSpec wav_spec;

    SDL_Init(SDL_INIT_AUDIO);
    if (SDL_LoadWAV("test.wav", &wav_spec, &wav_buffer, &wav_len) == NULL)
       {
           printf("Couldn't load wav file:  %s\n", SDL_GetError());
       }
    wav_spec.callback = fill_audio;

    if (SDL_OpenAudio(&wav_spec, NULL) < 0)
       {
           printf("Couldn't open audio device: %s\n", SDL_GetError());
           return (-1);
       }

    wav_pos = wav_buffer;
    SDL_PauseAudio(0);
    while (wav_len > 0)
       {
           SDL_Delay(50);
       }
    SDL_FreeWAV(wav_buffer);
    SDL_CloseAudio();
    return (0);
}

/*********************************************************/
/*      Callback function for playing audio              */
/*********************************************************/
void fill_audio(void *udata, Uint8 * stream, int len)
{
/*  Only play if we have data left */
    if (wav_len == 0)
       {
           return;
       }
/*  Mix as much data as possible */
    len = (len > wav_len ? wav_len : len);
    SDL_MixAudio(stream, wav_pos, len, SDL_MIX_MAXVOLUME);
    wav_pos += len;
    wav_len -= len;
}

[Martin Donlon]

Please! Feel free to throw together as many examples as you want. Examples are sorely needed int he new docs.

[Anonymous]

    Yes, I definately agree, your help will be greatly appreciated... Could you post an example of the function SDL_UpdateRects using a number of rectangles greater than 1? Thank You.

[Corey Virgil]

Something along these lines should do it.

(Sorry that took so terribly long, I haven't checked in on this page for awhile.)

                        /*******************************************************
                        gradient.c
                        ********************************************************/

                        #include <stdio.h>
                        #include <stdlib.h>
                        #include <SDL.h>

                        int main (int argc, char *argv[])
                        {
                        SDL_Surface *screen;
                        SDL_Rect section;
                        SDL_PixelFormat pixel;
                        int count1, count2;
                        Uint32 color;

                        SDL_Init (SDL_INIT_VIDEO);
                        atexit(SDL_Quit);
                        screen = SDL_SetVideoMode (800, 600, 0, SDL_HWSURFACE);

                        count2 = 255;
                        for (count1 = 0; count1 < 600; count1++)
                        {
                        section.x = 0;
                        section.y = count1;
                        section.w = 800;
                        section.h = 1;
                        color = SDL_MapRGB (screen->format, 0x00, 0x00, count2 - (count1 / 3));
                        SDL_FillRect (screen, &section, color);
                        }
                        SDL_UpdateRect (screen, 0, 0, 800, 600);

                        sleep (5);

                        return 0;
                        }

[Corey Virgil]

Oops, pasted the wrong code in.

Let's try this one...

/*******************************************************
multi_rects.c
********************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <SDL.h>

int       main (int argc, char *argv[])
{
  SDL_Surface *screen;
  SDL_Rect  multi_rect[4];
  SDL_PixelFormat pixel;
  Uint32    color;

  SDL_Init (SDL_INIT_VIDEO);
  atexit (SDL_Quit);
  screen = SDL_SetVideoMode (800, 600, 0, SDL_HWSURFACE);

  multi_rect[0].x = 10;
  multi_rect[0].y = 10;
  multi_rect[0].w = 80;
  multi_rect[0].h = 100;

  multi_rect[1].x = 50;
  multi_rect[1].y = 100;
  multi_rect[1].w = 80;
  multi_rect[1].h = 100;

  multi_rect[2].x = 500;
  multi_rect[2].y = 300;
  multi_rect[2].w = 80;
  multi_rect[2].h = 100;

  multi_rect[3].x = 600;
  multi_rect[3].y = 200;
  multi_rect[3].w = 80;
  multi_rect[3].h = 100;

  color = SDL_MapRGB (screen->format, 200, 0x00, 0x00);
  SDL_FillRect (screen, &multi_rect[0], color);

  color = SDL_MapRGB (screen->format, 0x00, 255, 0x00);
  SDL_FillRect (screen, &multi_rect[1], color);

  color = SDL_MapRGB (screen->format, 155, 155, 155);
  SDL_FillRect (screen, &multi_rect[2], color);

  color = SDL_MapRGB (screen->format, 255, 255, 255);
  SDL_FillRect (screen, &multi_rect[3], color);

  SDL_UpdateRects (screen, 4, &multi_rect);

  sleep (2);

  return 0;
}

[Ben Cummings]

I think this is great!  The one thing i've found lacking in all the SDL documentation is useful and small examples like this!  So far, i've just been using the demos listed on libsdl.org to try to figure things out because, other than for function reference, the existing documentation is fairly hard to digest, and in some places, completely inadiquate.  I think that if we can get a nice code base of SMALL examples of SDL, properly integrated with the existing documentation, the learning curve on SDL could dramatically decrease.

If you do get serious about producing these examples, i suggest you look through some of the demo code.  I'd even be willing to help you with that some, though a lack of time and skill with SDL will limit my abilities in this arena.

Anyway, SDL's documentation has come a long way, but we still have some distance to cover.  Good luck!

benc
pc-rpg project
ben c at wsnbc dot org

[Corey Virgil]

I'll be doing more of these in the near future.  I'm writing a gui lib using SDL, so throwing together little throw-away apps like this is part of my process of learning SDL anyway.  Might as well let others benefit from them.

I've got 10 MB of web space from my ISP that's currently unused.  If I get a chance this week, I'll clean these up and post them there with makefiles, etc...

If you can think of any specific examples you'd like to see, feel free to let me know. 

BTW, the next part I need to add to my gui lib is alpha blending, so that's got a good chance of being the next example I post.  The lib is going to provide a user interface similar to that on the TiVo.  I'll be opening a page for it here on sourceforge as soon as I get it into a slightly more useable state.