Table of Contents
- Brief Summary of BrightScript Components
- BrightScript statements that work with BrightScript Component Interfaces
- Intrinsic types and object types
- Use of wrapper functions on intrinsic types
- BrightScript XML Support
- Garbage Collection
- Threading Model
- Creating and Using Intrinsic Objects
- "m" The BrightScript "this pointer"
- Script Libraries
The BrightScript Component architecture and library are separate from BrightScript, but BrightScript requires them.
- All APIs exposed to BrightScript are exposed as BrightScript components. In other words, if a platform wants to expose APIs to be scripted, the platform must register a new BrightScript component.
- BrightScript has language features that are designed to work with BrightScript component Interfaces. These include: for each, print, the array operator, dot operator, and intrinsic objects.
- Fundamental BrightScript building blocks are implemented as BrightScript components. For example: Lists, Vector Arrays, Associative Arrays, and Objects.
Brief Summary of BrightScript Components
BrightScript Components are robust against version changes. In other words, scripts are generally backwards compatible with Objects that have undergone version improvements.
BrightScript Components keep a reference count and delete themselves when the reference count goes to zero.
A key BrightScript Component concept is the Interface. The term Interface is used here as it is in Java or Microsoft COM. An interface is a known set of member functions that implement a set of logic. In some ways an Interface is like a virtual base class in C++. Any script or C-compatible program can use an object's interface without regard to what type of object it is a part of, as long as it is familiar with a particular interface. For example, the roUrlTransfer component implements four interfaces: ifUrlTransfer, ifHttpAgent, ifSetMessagePort and ifGetMessagePort.
BrightScript statements that work with BrightScript Component Interfaces
The for-each statement works on any object that has an ifEnum interface. These include: Array, Associative Array, List, ByteArray, and MessagePort.
If the expression being printed evaluates to an object that has an ifEnum interface, print will print every item that can be enumerated.
In addition to printing the values of intrinsic types, PRINT will also print any object that exposes one of these interfaces: ifString, ifInt, ifFloat.
The wait function will work on any object that has an ifMessagePort interface.
Member access operator "."
The "." Operator works on any object that has an ifAssociativeArray interface (as well as on any BrightScript Component (when calling a member function)). It also has special meaning when used on roXMLElement or roXMLList.
Intrinsic types and object types
A variable may hold either an "intrinsic type" or an "object type". An intrinsic type is one of Integer, Float, Double, String, Invalid, Boolean or Function. An object type is one of Array, Associative Array or BrightScript Component. The most important difference is a variable containing an intrinsic type contains the value itself; that is, the Integer, Float, Double, etc. is contained within the variable. On the other hand, a variable containing an object type contains merely a pointer or reference to the actual object. Assigning an object type results in two pointers to the same object, while assigning an intrinsic type results in two copies of the same value, which can be modified independently of each other.
The same thing holds true when variables are passed as function parameters. If the variable is intrinsic, the function parameter is a copy of the original. But if the variable is object, the function parameter is merely an additional reference to the same object. That is, intrinsic variables are "passed by value", while object variables are "passed by reference".
Each object maintains a "reference count", which is the number of variables which refer to the object. The reference count is set to 1 when the object is created and a reference to it is saved in a variable. When an object's reference count drops to zero, the object is destroyed.
Note that after the last statement, since no variables refer to the object any longer, it would be impossible to use the object even if it were not destroyed.
Use of wrapper functions on intrinsic types
If an intrinsic types is passed to a function that expects an Object, a "wrapper" object will be created, assigned the correct value, and passed to the function. Wrapper objects are objects which behave like the intrinsic entities that they represent. For example, an integer may be converted to an roInt object, which can be used much like an ordinary integer, but it has object semantics. This automatic conversion to an object is sometimes referred to as "autoboxing".
A 4 roInt
B 4 Integer
Will cause an error since the dot operator binds tighter than unary negation. Use:
BrightScript XML Support
BrightScript supports XML via two BrightScript Components, and some dedicated language features. The BrightScript Component roXMLElement provides support for parsing, generating, and containing XML. In addition, the roXMLList object is often used to hold lists of roXMLElement, and implements the BrightScript standard ifList interface as well as the ifXMLList interface. Language features are provided via the dot operator, and the @ operator. BrightScript XML support is limited to UTF-8 encoded content.
- When applied to an roXMLElement, the dot operator returns an roXMLList of children that match the dot operand. If no tags match, an empty list is returned.
- When applied to an roXMLList, the dot operator aggregates the results of performing the dot operator on each roXMLElement in the list.
- When used on XML, which is technically case sensitive, the dot operator is still case insensitive. If you wish to do a case sensitive XML operation, don't use the dot operator. Use the XML member functions.
The @ operator can be used on an roXMLElement to return a named attribute. It is always case insensitive (despite the fact that XML is technically case sensitive). When used on an roXMLList, the @ operator will return a value only if the list contains exactly one element.
For example, if the file "example.xml" contains the following:
Will return an roXMLList with three entries.
Will return an roXMLElement reference to the first photo (id="3131875696").
Will return an roXMLList reference containing the photos tag.
Will return the string 100.
Use the GetText() method to return an element's text.
For example, if the variable booklist contains this roXMLElement:
<book lang=eng>The Dawn of Man</book>
will print "The Dawn of Man", and
will print "eng".
BrightScript will automatically free strings when they are no longer used, and it will free objects when their reference count goes to zero. This is done at the time the object or string is no longer used; there is no background garbage collection task. This results in very predictable "garbage collection" – there are no unexpected stalls in execution.
A "mark and sweep" garbage collection is run after a script executes, or can be manually forced to run via the debug console. A script can force the Garbage Collector to run via the RunGarbageCollector() function. The Garbage Collector's purpose is to clean up objects that refer to themselves or have other circular references (which are not managed by the normal reference counting garbage collection).
Events in BrightScript center around an event loop and the roMessagePort BrightScript Component. Any BrightScript Component can be posted to a message port. Typically these will be Objects that are designed to represent an events. For example, the roFilesystem class posts events of type roFilesystemEvent.
A BrightScript script runs in a single thread. Multiple threads cannot be created in a BrightScript program. The general rule of thumb is that BrightScript Component calls are synchronous if they return quickly, or asynchronous if they take a long time to complete. For example, class roArray methods are all synchronous. But if "roVideoPlayer" is used to play a video, the Play() method returns immediately while video continues to play (it is asynchronous). As the video plays, it will post events to a message port. Typical events would be "media finished" or "time x reached". Some components have a choice of synchronous or asynchronous methods; for example roUrlTransfer has methods GetToString() which is synchronous (returns only after the transfer is complete) and AsyncGetToString() which is asynchronous (returns immediately and the transfer continues in the background).
This threading model means that the script writer does not have to deal with mutexes, condition variables, and other synchronization objects. The script merely receives and processes messages to handle events happening in the background.
BrightScript uses the following scoping rules:
- BrightScript does not support global variables. Except, there is one hard-coded global variable "global" that is an interface to the global BrightScript Component. The global component contains all global library functions. There is also a global context that can be accessed via the GetGlobalAA(). If in function scope and that function is not a method in an object, "m." also references the global associative array accessed with GetGlobalAA().
- Functions declared with the FUNCTION statement are at global scope, unless they are anonymous, in which case they are local scope.
- Local variables exist with function Scope. If a function calls another function, that new function has its own scope.
- Labels exist in function scope.
- Block Statements (like FOR-END FOR or WHILE-END WHILE) do not create a separate scope.
Creating and Using Intrinsic Objects
In most of this manual we use the term "object" to refer to a "BrightScript Component". These are C or C++ components with interfaces and member functions that BrightScript uses directly. Other than a few core objects that BrightScript relies upon (roArray, roAssociativeArray, roInt, etc.) BrightScript Components are platform specific.
You can also create "intrinsic" objects in BrightScript itself to use in your scripts. These act in some ways like Components; for example, the syntax to invoke a method in a Component or in an intrinsic object is identical: "object.function()". However, to be clear, these are not BrightScript Components. There is currently no way to create a BrightScript Component in BrightScript, or to create intrinsic objects that have interfaces (they only contain member functions, properties, or other objects).
An intrinsic object is simply an roAssociativeArray which contains function references. When a function is called "from" an Associative Array, a special pointer named "m" is accessible inside the function, which refers to the Associative Array. A "constructor" in BrightScript is a normal function at global scope that creates the Associative Array and fills in its member functions and properties.
"m" The BrightScript "this pointer"
A BrightScript object is an roAssociativeArray which contains function pointers. When a member function is called "from" an AssociativeArray, the special variable "m" is set to point to that AssociativeArray. "m" is accessible inside the called function to access other data in the AssociativeArray object.
get: <bsTypedValue: Function>
set: <bsTypedValue: Function>
In addition to the platform BrightScript components discussed in Brief Summary of BrightScript Components, BrightScript enables platform BrightScript libraries to be used in your scripts.
BrightScript libraries are .brs files that are provided by the platform and compiled into your application when directed via the "Library" keyword to make additional functions available.
The firmware provides some common libraries under the system library directory "common:/LibCore".
Additional libraries may be provided by the platform for specific usage purposes.
The common library file sources can be viewed from the debug console:
BrightScript> bslCore = ReadAsciiFile("common:/LibCore/v30/bslCore.brs")
BrightScript> print bslCore
This library provides platform constant definitions as well as some common utility functions.
bslBrightScriptErrorCodes() as Object
- Returns an roAssociativeArray with name value pairs of the error name and corresponding integer value, for example ERR_OKAY = &hFF.
bslGeneralConstants() as Object
- Returns an roAssociativeArray with name value pairs of system constants, for example MAX_INT = 2147483647.
bslUniversalControlEventCodes() as Object
- Returns an roAssociativeArray with name value pairs of the remote key code (buttons) constants, for example BUTTON_SELECT_PRESSED = 6.
AsciiToHex(ascii as String) as String
- Returns the hex encoded string, for example AsciiToHex("Hi!") = "486921".
HexToAscii(hex as String) as String
- Returns a string that is the hex decoded string, for example HexToAscii("486921") = "Hi!".
HexToInteger(hex as String) as Integer
- Returns the integer value of the passed in hex string.
This library includes 2D graphics helper functions on top of the native components.
Object dfNewBitmapSet(String filename)
The goal is to enable simple xml descriptions of graphics resources like bitmaps, regions, sprites, animations, and layouts to be used in your games. The library handles parsing, loading, rendering, and animation of sprites sheets (multiple images in a single png file).
- filename is the path to an XML file that contains info about bitmap regions, animation frames, and ExtraInfo metadata (any fields you would like) about resources used in 2d games.
- Returns an roAssociativeArray with the following name value pairs:
- ExtraInfo :roAssociativeArray
- Contains any name value pairs the designer desires.
- Regions : roAssociativeArray of name, roRegions pairs
- The roAssociative array returns a set of Regions from Region tag information from the xml.
- Used to describe regions of a bitmap
- Bitmap contains parameters: name, filename where filename is a .png, .gif, or .jpg file
- Region contains parameters: name, x, y, w, h and is a subtag of a bitmap
- Animations : roAssociativeArray of name, roArray of roRegion pairs.
- The top level roAssociativeArray is the animation name with a value of an array of frames that represent the animation
- Each frame is an roRegion that is represented in the xml by the "use" parameter. The use parameter refers to a previously defined Bitmap.Region returned in the Regions info.
- Animation frame descriptions can be used by the roSprite and roCompositor components.
- Backgrounds : roAssociativeArray of name, path pairs.
- Backgrounds do not create bitmaps at this point
- Use in conjunction with dfSetBackground() to manage backgrounds
- ExtraInfo :roAssociativeArray
dfDrawMessage(dest as Object, region as Object) as Void
- dest is an roScreen/roBitmap/roRegion and region is an roRegion
- greys the entire dest region and draws it the region centered on the drawable dest.
dfDrawImage(dest as Object, path as String, x as Integer, y as Integer) as Boolean
- Returns True if successful
- Creates a bitmap out of the image stored in the filename "path" and draws it at position (x,y) of the drawable dest.
dfSetupDisplayRegions(screen as Object, topx as Integer, topy as Integer, width as Integer, height as Integer) as Object
- Helper function to setup screen scaling with supplied pillar box or letterbox images to fill the entire screen.
- screen is an roScreen
- topx and topy are the coordinates of the upper left hand corner of the main drawing region
- Width and height is the size of the main drawing region
- Returns an associative array containing the following roRegions
Main: main drawable region
Left: left region if there is pillar box area on the left
Right: right region if there is a pillar box area on the right
Upper: upper region if there is a letterbox area at thetop
Lower: lower region if there is a letterbox area at the bottom
When using these regions as drawables, your graphics will be translated and clipped to these regions.
Object dfSetBackground(String backgroundName, Object backgrounds)
- dfSetBackground helps manage the limited video memory. The video memory does not currently run a defragmenter, and is very limited. These constraints make it important that large bitmaps (like backgrounds that fill the entire screen) are only allocated when needed. It is also helpful if you set your first initial background very early in your program, and then immediately replace the background after it is no longer in use. This helper function supports this background management for your application.
- backgroundName is a key for the Backgrounds roAssociative array of backgrounds.
- Backgrounds is an roAssociative array of background name keys and file path string values
- This function creates an roBitmap out of the background image file and returns a region the size of the entire roBitmap.
If spriteMap.xml contains the following:
BrightScript> xml = ReadAsciiFile("pkg:/images/map.xml")
BrightScript> bitmapset = dfNewBitmapSet(xml)
BrightScript> print bitmapset.regions
Background: <Component: roRegion>
game-over: <Component: roRegion>
title-screen: <Component: roRegion>
water_strip.a: <Component: roRegion>
water_strip.b: <Component: roRegion>
water_strip: <Component: roRegion>
BrightScript> print bitmapset.animations.water
BrightScript> dfDrawMessage(screen, bitmapset.regions["game-over"])
BrightScript> REM screen now shows gameover.png image centered on screen