Welcome to the Cascade Library Reference Manual

Introduction

The Cascade Library is a high-level, high-impact, easy to use, resource efficient library for the development of high-performance media-rich applications on the Linux operating system. It's primary purpose is to provide application developers with the tools they need to develop applications on Cascade Platforms such as the Roku Deschutes 1000.

The Cascade Library is designed to provide easy to use, high-performance, powerful facilities to the programmer without interfering with the programmer's native command of Linux programming. Generally speaking, the CascadeLibrary provides classes for inter-process and inter-thread communication, 2d graphics, a/v streaming, application and window control, and user- interface widgets.

The Cascade Library is divided into the following sections:

App classes:	CascadeApp, CascadeAppMessageSink, CascadeInput, CascadeMountMessage, CascadePowerLED, CascadePowerLEDMessage, CascadePowerMessage, CascadeTimer, CascadeWindow
A/V classes:	CascadeAudioPlaybackDevice, CascadeMP3Player, CascadeMPEGFile, CascadeMPEGPlayer, CascadeWAVPlayer
Graphics classes:	CascadeBitmap, CascadeColor, CascadeDims, CascadeFont, CascadePoint, CascadeRect, CascadeScreen, CascadeScreenMessage
Interprocess classes:	CascadeMessage, CascadeSemLock, CascadeSharedList, CascadeSharedMemZone, CascadeWormhole
Interthread classes:	CascadeMonitor, CascadeMutex, CascadeThread
Utility classes:	CascadeArray, CascadeDirBrowser, CascadeDirectory, CascadeDirScanner, CascadeElapsedTime, CascadeFile, CascadeFSObject, CascadeJpegFile, CascadeSettings, CascadeSpawn, CascadeString, CascadeStream, CascadeFileStream, CascadeTime, CascadeTokenArray
User Interface Widget classes:	CascadeWidget, CascadeButtonWidget, CascadeLabelWidget, CascadePictureWidget, CascadeSpinnerWidget, CascadeVesselPanel

Terminology: Processes and Threads

Throughout this documentation we will be referring to processes and threads. A process in Cascade parlance refers to a Linux process or group of Linux processes that all share the same address space (and other Linux resources such as file descriptors). Typically this refers to a Linux program that may or may not spawn multiple pthreads. When a Linux program executes, we refer to the thread of execution that calls function main as the process' main thread. Unless a process spawns 1 or more additional pthreads, the process' main thread is the only thread in the process. Threads, then, are defined as threads of execution that share the address space with other threads of execution running in the process. In Cascade, the class CascadeThread provides an easy mechanism for spawning multiple threads in your process, so many Cascade programs will likely have multiple threads within their process.

Installation

Installing the Cascade Libarary is easy. Here's how:

1. First make the Cascade Public header files available to your compiler:
   • Either add a -I compiler directive in your makefile to point to the "include" directory located at the top level of your Cascade Library distribution.
   • Or put the "cascade" directory located inside this "include" directory into an include directory that is already on your include path (e.g. /usr/local/include).
2. Next, place libCascade.so in a spot where your linker and the loader can find it, either by <the official linux process to register libraries>, or by adding the directory path of libCascade.so to your LD_LIBRARY_PATH environment variable.

Using the library

Using the Cascade Library is easy. To use the Cascade Library (hereinafter referred to as becoming a Cascade Library client) simply include a Cascade Library header file in your code (usually <cascade/Cascade.h>), reference (use) an object in the Cascade public interface, link against the Cascade Library and you're off an running. Here's an example:

whitescreen: a program to paint the screen white:

    // FILE: whitescreen.cpp
    #include <cascade/Cascade.h>

    int main(int argc, const char ** argv)
    {
        CascadeScreen screen;
        screen.FillRect(screen.GetRect(), CascadeColor(255, 255, 255));
        return 0;
    }
    

compiling and linking whitescreen.cpp:

    host% gcc -c whitescreen.cpp -o whitescreen -lCascade
    

A few words on header file inclusion

The Cascade Public Interface is designed so that clients need only include the header files they need at any particular time, e.g.

#include <cascade/graphics/CascadeScreen.h>

Most clients, however, will simply

#include <cascade/Cascade.h>

as it is a convenient way to gain access to the entire Cascade Public Interface all at once. For this reason, all examples in this documentation will simply include <cascade/Cascade.h>. Be assured that the entire Cascade Public Interface has been designed to be extremely efficient (inclusion-wise) and compatible with any other interfaces the client may wish to include. In the unlikely event you have difficulty including <cascade/Cascade.h>, consult CascadeTypedefs.h

---