Scene Basic Structure

To start, let's go through the basic structure of a scene. Generally, the programmer is free to organize the source code of their scene however they want. There are however some necessary callbacks and boilerplate code that need to be written.

First, create a folder called CatPad under App/Scenes then create a header and source file called BM_Scene_CatPad.h and BM_Scene_CatPad.c. The header file should look like the following:

//  BM_Scene_CatPad.h
#pragma once

#include "arm_math.h"
#include "BM_Scene.h"           //  Contains typedefs necessary for building scenes
#include "BM_ErrorCodes.h"      //  Error codes
#include "BM_RenderEngine.h"    //  For calling rendering functions
#include "BM_Common.h"          //  For calling convenience macros and fade in/out envelopes if the scene crossfades audio in some way
#include "BM_Sprite.h"          //  Contains struct definitions for storing sprites
#include "BM_UserIOServices.h"  //  For calling functions that read button states

//  For this scene, we will use the SV Filter and also import misc utilities
//  Include the appropriate audio effects for your particular scene here
#include "MW_AFXUnit_SVFilter.h"
#include "MW_AFXUnit_MIscUtils.h"

//  Include sprite header for the scene
//  We haven't created this file yet so you will get compiler errors.  We will cover this in the next section
#include "BM_Assets_CatPad.h"

//  A scene must have an initialization function with the following signature
BM_Error BM_Scene_CatPad_init(BM_Scene *scene);

// Necessary callbacks to implement
void BM_Scene_CatPad_update(void* data);
void BM_Scene_CatPad_draw();
void BM_Scene_CatPad_processAudio(float32_t *buffer, const size_t bufferSize);
void BM_Scene_CatPad_handleUserIO();
void BM_Scene_CatPad_reset();

// Other functions and variables necessary for the scene (up to the programmer)

As a convention, scenes and their associated variables/functions are prefixed by BM_Scene_[Scene Name]. This is to avoid name clashes with similarly named functions across other source files.

The include directives bring in necessary headers needed for the scene to operate. Since we want to incorporate an SV Filter into our scene, we will include the MW_AFXUnit_SVFFilter.h header. This header is part of the AudioFXUnits library.

A scene must include an initialize function (which is called by the active controller on start up) and must accept a pointer to a BM_Scene instance (provided by the active controller) and return an error code.

The rest of the functions are the callback functions that our scene must implement.

Before we implement the functions, let's first talk about importing graphical assets into BitMasher.