Volume Number: 13 (1997)
Issue Number: 1
Column Tag: Betech™

BeOS Plug-ins

By William Adams, Be, Inc.

Easy image import using the BeOS plug-in architecture

The computer software industry is prone to intergalactic paradigm shifts. When a company comes out with something new, and they want to make a lot of money, they call it a paradigm shift. This is often a code word that says: we have something that is so different from everything else, it's actually difficult to learn, but we spent a lot of money producing it, so we are calling it a new paradigm.

Paradigm shifts are not always difficult. When Xerox invented a windows based interface that utilized a mouse, you could call this a paradigm shift. It sharply diverged from the traditional text-based, keyboard bound interface of the day and provided a method of interaction with computers that was easier and faster for many users. If you cannot get a paradigm adopted, (it becomes too expensive due to learnability or other factors) it is worth about $0.20.

PC's and mainstream operating systems have been around for about 15 years. This is also true for some of the hardware that supports them. The operating system is a crafty little piece of software that most end users should not care much about beyond the extent that it enables them to go about doing their work efficiently. To a programmer, the operating system should make it easy to create compelling and useful software with the least amount of effort. It should run the software as efficiently as possible on any targeted hardware platform. It must be flexible and dynamic enough to adapt and change as time progresses so applications do not begin to run slower with each release.

The commodity software market is still very young, with only 15 years of real commercial growth. This youth is most evident in the systems that were available at the beginning of that period. The machines of the day were pitifully slow and very constrained by resources such as RAM and disk space. At the time, a network connection was a 300 baud modem linked to a timesharing system. TCP/IP protocol stacks and Ethernet cards were merely chalk dust. Given this crucible of development, it's no wonder that when these new technologies began to show up, the OS and programming tools began to grow warts. Tack on a device driver here, an Ethernet card there, and pray that it all still works. If you are a developer, pray that the end user is utilizing hardware for which you have a driver.

Thankfully, systems adapt, standards emerge, drivers are written, abstraction layers are added, and paradigms are shifted. The Be Operating System (BeOS) is not so much a paradigm shift as it is a convergence, consolidation, and re-alignment. The engineers at Be are all students of OS design and API production. Be presents the opportunity to do it all over again. In "doing it right," we are not necessarily seeking to re-invent the wheel, only to get the right balance. You can view us as OS chiropractors. Current OS offerings are like elderly gentlemen sagging under their own weight. Things are just a little misaligned in most commodity OS's, and the BeOS straightens things out.

We can look at two vertebrae of the typical misaligned OS - one is data sharing, the other is command processing. First, let's look at data sharing. I have one application, or portion of an application, and I want to share data with another application. A typical method of sharing is the copy/paste combination. I might select a piece of an image in a paint program and paste it into another. Another method is to drag a file representation from a file browser onto the paint canvas. Alternately, I may receive an image from a server process, or from across a network.

For many programmers, these various operations would each be represented by a distinctly different API in a misaligned OS. Since there are many APIs to learn, programmers will not implement all of the operations. Without continuous support for many common operations, the road a user must travel to get to the end of any particular task becomes rutted and bent.

The other major misaligned vertebrae have to do with data processing. From the resource constrained crucibles of software development of 15 years ago emerged coding styles and techniques that should seem like quaint anachronisms in the blinding light of today's resource heavy devices. Another Xerox invention, the SmallTalk language, provided what is not really a paradigm shift as much as it is a sanity check.

Computers are not yet artificial life forms that we expect to work and learn independently for the betterment of the universe. They are generally clunky, noisy boxes that we shove endless amounts of data into and have them transform it into a different form, then spit it back out. Computer's process data - no matter what form that data takes, there are methodologies that can be adhered to in order to maintain consistency and generate expected results. We expect good software to perform this way. It will do you no good if the computer in your car decides to turn on your lights instead of deploy your airbag in an accident.

The SmallTalk environment introduced a programming methodology known as Model, View, Controller. In this methodology, the model is the data of the system. This is true for a word processing system, a game, or an accounting package. The view is simply the interface through which a user interacts with the system. This includes all external influences such as displays, mice, keyboards, printers, speakers, etc. The controller is the mechanism by which the view (interface) can affect changes on the data. For exeample, we press the delete key to delete the selected text in a word processor. It is extremely beneficial to the developer if the programming environment provides a mechanism adhering to this model. A misaligned system provides no such mechanism, and thus leaves it to all developers to re-invent the same mechanism. Such a programming community is not working efficiently, and could be more innovative.

One of the primary target markets for the BeOS is multimedia authors and editors. This crowd generally uses products such as PhotoShop, Premiere, Fractal Design Painter and the like. One of the biggest problems encountered by this set of users is inter-operability between applications. Sharing files and effects across applications is sometimes time consuming and frustrating. To solve this problem, we present Rraster, an image viewer with a window. You can drag and drop files onto the icon and the application will open up and display the image. You can also copy and paste a selection between applications, or onto the same canvas.

In our sample code we will demonstrate how to extend an application to support a wide variety of graphics file formats, without having to wait for the original manufacturer to do so. This capability is similar to PhotoShop plug-ins, as well as in other products. We start with a general specification of what the program should do:

• Give the user a way of dragging and dropping graphic images from the file browser onto the interface and have them displayed.
• Provide a mechanism to support drag and drop pasting from another source.
• Provide the ability to accept any file format for which a codec is available.

The last point is the most important, and the rest is the supporting framework. An image codec translates an image from one format to another. For example, a GIF codec would know how to decode and encode an image of the GIF format. First, we must have a native format that all codecs can understand. This format is represented by the following GfxImage structure:

typedef struct GfxImage {
    // image data
 void *data;
    // image dimensions
 long width;
 long height;    
 long bytes_per_row;
    // 8-bit or 32-bit
 color_space type; 
 int file_format;
 int color_format;
 int num_colors;
    // colormap, if type == 8_BIT
 rgb_color palette[256];
    // long format identifier, set on load
 char full_info[128];
    // short format identifier, set on load
 char short_info[128];  
    // image comment; saved if format supports it
 char *comment;
    // # of page files, basename of page files
 if >1 int numpages;    
 char pagebname[64];  
} GfxImage;

This is not the most complete representation that a raster image could possibly have, but it captures the essence of many file formats in a clear way. The BeOS supports a native format for bitmap information. It is the BBitmap class. This class is intended to display information on the screen. We could utilize this class directly instead of intermediary, but using the GfxImage structure gives us greater flexibility in what we can do with the images that we load.

An ideal programming interface for using images would be something like

GfxImage * CreateRasterFromFile(BFile *);
GfxImage * CreateRasterImage(char *fname);
int WriteRasterImage(GfxImage *, BFile*);
int WriteRasterImage(GfxImage *p, char *fname);

This is an easy interface that would allow a programmer to write code that is as clean and simple as

GfxImage *newImage = CreateRasterImage("MacTech.gif");
DisplayImage(newImage);

The road you must travel to get to such easy programming is not that difficult, nor long. We need code that will do three things:

• Identify a file as something that we can turn into a GfxImage structure.
• Create a GfxImage from the file.
• Write a GfxImage to the file.

We use Metrowerks' export pragma to ensure that our symbols are exported so that they can be found when the module is loaded at run-time.

These functions are used for additional identification and credit notices. A host application might use them to display in an about box, or in some other fashion.

#pragma export on
char *rrasaddon_IDName();
char *rrasaddon_IDAuthor();
char *rrasaddon_IDNotice();
char *rrasaddon_IDEncoder();
char *rrasaddon_IDDecoder();
float CanCreateImage(void *bytes, long byteLen);
GfxImage *CreateImage(BFile *file);
#pragma export off

char *IDName = "GIF Codec";
char *IDAuthor = "William Adams";
char *IDNotice = "Copyright Be Inc. 1996";
char *IDEncoder = "IDgif";
char *IDDecoder = "IDgif";

char *rrasaddon_IDName()
{
 return IDName;
}

char *rrasaddon_IDAuthor()
{
 return IDAuthor;
}

char *rrasaddon_IDNotice()
{
 return IDNotice;
}

Some image codecs utilize very large libraries. This is true for formats such as TIFF and JPEG. For these formats, specify an associated module that can be used to decode an image. The rrasaddon_IDEncoder() and rrasaddon_Decoder() functions specify the names of these external modules.

char *rrasaddon_IDEncoder()
{
 return IDEncoder;
}

char *rrasaddon_IDDecoder()
{
 return IDDecoder;
}

By using three separate modules for identification, decoding, and encoding, we have the flexibility to only load the identification module without having to load all the rest of the code with it. If a module is small enough that it does not make sense to have separate decoders and encoders, then they can all be in one file. The IDEncoder, and IDDecoder strings point to the name of the file that should be loaded to perform codec tasks. If they are the same as the current module, then nothing else will need to happen. If they are not, when it comes time to perform a function, the appropriate module will be loaded.

We want to have the ability to load the best module for the job from within our application. We give the module a chance to advertise its confidence that it can perform a decoding task. It is passed a chunk of data from the beginning of the file, and from this it must determine whether or not it would be able to perform the task. The module returns a 0.0 to 1.0 float value. If it cannot perform any actions on the data, it would return a 0.0 value. If it is certain that it could decode the image completely to spec, then it would return a 1.0 value. If it is somewhere in between, (it could decode some, but not all variants) it might return a 0.8 value.

float
CanCreateImage(void *data, long dataLen)
{
 if (dataLen < 6)
 return 0.0;
 
 if (strncmp((char *) data,"GIF87a", (size_t) 6)==0 ||
 strncmp((char *) data,"GIF89a", (size_t) 6)==0)
 return 1.0;

 return 0.0;
}

CreateImage() is the meat of the decoding process. We assume that the module was already asked whether it can decode the image, and that we have the BFile object to create an image from. It opens the file, seeks to the beginning, and calls the ReadGIF function.

GfxImage *
CreateImage(BFile *file)
{
 if (!file)
 return 0;
 
 GfxImage *newImage = 0;  
 
 int imageNumber = 1;
 
 file->Open(B_READ_ONLY);
 file->Seek(0, B_SEEK_TOP);
 
 newImage = ReadGIF(file, imageNumber);

 return newImage;
}

The ReadGIF function is a typical GIF decoding code. It will turn the BFile data into a GfxImage structure, then return it to the caller. The WriteImage function is similar. At this point, we have a nice little function library to create GfxImages from GIF encoded files. You could just link this into your application and you would be set. However, we still have not achieved the "one call does it all."

Dynamically loading modules, searching for symbols, and calling function pointers are all doable, but it's not code that you want to keep writing. It is similar to the BSD socket's code. Every time you write it there is opportunity for mistakes. We create the GfxCodec object that performs exactly these tasks. We do not want to have to write a new sub-class of GfxCodec for every new graphic format that comes along. If we did, we would have to re-link the application for each new addition.

class GfxCodec 
{
public:
 GfxCodec(BDirectory *, BFile* );
 ~GfxCodec();

virtual float  CanCreateImage(BFile *);
virtual GfxImage * CreateImage(BFile *);
virtual voidWriteImage(GfxImage*, BFile *);
 
virtual bool IsValid();
virtual void Print();
 
    // Pointer to next codec so a chain can be created easily.
GfxCodec *next;  
protected:

    // Informational stuff so that we can identify the add-on and find other parts.
 BDirectory fBaseDirectory;
 char   fBaseName[B_FILE_NAME_LENGTH]; 
 
    // Function pointers in the identifier module with useful information.
 char *(*addon_IDName)();
 char *(*addon_IDAuthor)();
 char *(*addon_IDNotice)();
 char *(*addon_IDEncoder)();
 char *(*addon_IDDecoder)();

 float  (*addon_CanCreate)(void *, long);
 GfxImage *(*addon_CreateImage)(BFile *);
 long (*addon_WriteImage)(BFile *);
 
 image_id fIdentifier;
 image_id fDecoder;
 image_id fEncoder;

private:

};

The GfxCodec object is constructed with BDirectory and a BFile object. These tell the codec where it can find the add-on code that will be used. In the BeOS, an add-on is nothing more than a shared library. The PowerPC and PEF format allow for dynamically loading code at run-time, having the ability to load code and get symbols and function pointers. This ability is at the heart of our code's extensibility. The constructor for the codec looks like this:

GfxCodec::GfxCodec(BDirectory *directory, BFile* a_file)
 : addon_IDName(0),
 addon_IDAuthor(0),
 addon_IDNotice(0),
 addon_IDEncoder(0),
 addon_IDDecoder(0),
 addon_CanCreate(0)
{
 a_file->GetName(fBaseName);
 fBaseDirectory = *directory;
 fIdentifier = B_ERROR;
 fDecoder = B_ERROR;
 fEncoder = B_ERROR;
 next = 0;
    // Try to load in the identifier module based on the name
 fIdentifier = load_add_on(a_file);
 
 if (B_ERROR != fIdentifier)
 {
 fDecoder = fIdentifier;
 fEncoder = fIdentifier;
 
 long error;
 
    // We have successfully loaded the module, now get pointers to some
    // functions we expect to exist.
 error = get_image_symbol(fIdentifier, 
 "rrasaddon_IDName__Fv", 2, &addon_IDName);
 error = get_image_symbol(fIdentifier, 
 "rrasaddon_IDAuthor__Fv", 2, &addon_IDAuthor);
 error = get_image_symbol(fIdentifier, 
 "rrasaddon_IDNotice__Fv", 2, &addon_IDNotice);
 error = get_image_symbol(fIdentifier, 
 "rrasaddon_IDEncoder__Fv", 2, &addon_IDEncoder);
 error = get_image_symbol(fIdentifier, 
 "rrasaddon_IDDecoder__Fv", 2, &addon_IDDecoder);
 error = get_image_symbol(fIdentifier, 
 "CanCreateImage__FPvl", 2, &addon_CanCreate);
 error = get_image_symbol(fIdentifier, 
 "CreateImage__FP5BFile", 2, &addon_CreateImage);
 }
}

An add-on is loaded into the system using the load_add_on() function. This returns a value that identifies the module that was just loaded. Once a module is loaded, you can proceed to poke around to get symbol information and function pointers.

The get_image_symbol() functions assign the pointer to the desired function or symbol to the given argument. There are several functions in the add-on module. Five of them deal with identifying the module and related modules. For example, with the GIF add-on, the functions return information relevant to encoding and decoding GIF images. Those funny function names come from the fact that the compiler mangles the names before sticking them in the library. We must ask for the symbols using their mangled names. There is a standard mechanism that enables us to find out the mangled names of all our symbols, so we don't have to question whether we're doing it right.

The GfxCodec acts as a wrapper for many calls in the add-on module. The CanCreateImage() method utilizes the function pointer to the addon_CanCreate function that has been loaded from the module. It takes care of reading a bit of the file and passing this data onto the module for identification.

float
GfxCodec::CanCreateImage(BFile *file)
{
    // Early exits for lack of resources
 if (!file)
 return 0;

 if (!addon_CanCreate)
 return 0.0;

 char data[128];
 long buffSize =128;
 long dataLen=128;
 file->Open(B_READ_ONLY);
 file->Seek(0,B_SEEK_TOP);
 dataLen = file->Read(data, buffSize);

 float confidence =  addon_CanCreate(data, dataLen);
 return confidence;
}

CreateImage() behaves similarly. It utilizes the dynamically loaded function to create an image from the file. For simplicity, we assume that the image decoding module is the same as the identification module.

GfxImage *
GfxCodec::CreateImage(BFile *file)
{
 GfxImage *newImage = 0;
 
    // Early return due to lack of resources
 if (!file || !addon_CreateImage)
 {
 printf("GfxCodec::CreateImage() - leaving early\n");
 return 0;
 } 

    // Now that we have the decoder add-on, we should be able to call the decode 
    // function and get an image out.
 newImage = addon_CreateImage(file);
 
 return newImage;
}

Given the GfxCodec class, we can now write code that will allow us to dynamically load an add-on module to decode images. The task is still a bit cumbersome, but we are building piece by piece to get to our promised "one function does it all." Now we need some management.

BDirectory gAddOnsDirectory;

void
SetAddOnsDirectory(record_ref aRef)
{
 char name_buf[1024] = {‘\0'};
 
 gAddOnsDirectory.SetRef(aRef);
 gAddOnsDirectory.GetName(name_buf);
 
 ReloadCodecs();
}

First of all, we need some way of telling the add-on manager where to look for modules. SetAddOnsDirectory() performs this simple task. A record_ref is the lowest level representation of things like BFiles and BDirectories in the BeOS. A record_ref might be passed to you when a directory is dropped onto the interface, or you might get it from the startup directory of the application. It may even be stored somewhere in the system database. No matter where it comes from, we just need to point our directory at it.

void  
ReloadCodecs()
{
 image_id tmpID;
 GfxCodec *tmpCodec;
 
    // Iterate through the current codec list
 while (gCodecList)
 {
 long error = 0;
 
 tmpCodec = gCodecList->next;
 
 delete gCodecList;
 gCodecList = tmpCodec;
 }

We now want to clear out the current codec list because we think it is no longer valid. You could skip this step and hop from directory to directory loading in as many modules as you like. A good extension would also be to save the list persistently so it would be loaded automatically the next time.

    // If we don't have an add-ons directory, then just return immediately.
    // This is one way of wiping out the add-ons
 if (gAddOnsDirectory.Error() == B_ERROR)
 {
 printf("ReloadCodecs - add-ons directory not valid.\n");
 return;
 }
 
    // Now traverse the current directory looking for new codecs to build.
 long index;
 BFile a_file;
 BDirectory a_dir;
 long file_count, dir_count;
 record_ref *ref_vector;
 char name_buf[B_FILE_NAME_LENGTH]; 

 file_count = gAddOnsDirectory.CountFiles();
 ref_vector = new record_ref[file_count];

We get the list of record_refs that represent all of the files in the specified directory.

 gAddOnsDirectory.GetName(name_buf); 
 gAddOnsDirectory.GetFiles(0, file_count, ref_vector);
 
 for (index = 0; index < file_count; index++) 
 {
 GfxCodec *newCodec = 0;
 
    // For each of the files found in the directory, try to make a GfxCodec out of it.
 if (a_file.SetRef(ref_vector[index]) < B_NO_ERROR)
 continue;
 
 newCodec = new GfxCodec(&gAddOnsDirectory, &a_file);

If the codec was not constructed for some reason, or it is invalid, then we will not bother trying to add it to the list.

 if (!newCodec || !newCodec->IsValid())
 continue;

Make the new codec the beginning of the list, if the list is currently blank. Otherwise, add it to the end of the list.

 
 if (0 == gCodecList)
 gCodecList = newCodec;
 else
 tmpCodec->next = newCodec;
 tmpCodec = newCodec;
 }

 delete [] ref_vector;
}

The ReloadCodecs() function is the workhorse of the management functions. It will scan through the specified modules directory and create a new GfxCodec object for each of the identifier modules that it finds. You can put all sorts of things in the directory and not worry about getting garbage GfxCodecs.

Of particular interest is the GfxCodec::IsValid() method. A GfxCodec must have two things to be considered valid. First, it must have loaded at least the identifier module. Second, that module must contain the rrasaddon_IDName() function. This is what prevents garbage from polluting our codec list. Random files, and other shared libraries won't have this function, so they won't load. You can even place the encoder and decoder modules in the same directory as the identifier module without fear of the wrong module being loaded, since the decoder and encoder modules won't have the rrasaddon_IDName() function. This gives us the flexibility to split our libraries into smaller manageable modules. It also allows us to randomly load new modules by just dropping them into the same directory.

bool
GfxCodec::IsValid()
{
 return ((B_ERROR != fIdentifier) && (addon_IDName));
}

We are inching even closer to that single function nirvana for loading images. We just need a bit more support, and we're all set.

FindImageDecoder() performs the mundane task of searching through the list of GfxCodecs that are currently loaded, and finding one that suits our needs. It traverses the list asking each module how confident it is that it can perform the task of decoding the image. Each module takes a crack at it, and the best module wins. This loop can be done differently if you want to give all modules a chance, or if modules will be reporting values higher than 1.0.

Now that we have a way of finding the right module for the job, all that is left is to write our one line function. CreateRasterFromFile() is our final product that ties it all together. It looks for a suitable module, and upon finding one, asks to create the image.

static GfxCodec *
FindImageDecoder(BFile *file)
{
 GfxCodec *candidate = 0;
 GfxCodec *tmpCodec = gCodecList;
 float confidence = 0.0;
 
    // Early exit if there is no file
 if (!file)
 return 0;
 
 
    // Traverse the list
 while (tmpCodec && confidence < 1.0)
 {
 float newConfidence = 0.0;
 newConfidence = tmpCodec->CanCreateImage(file);
 if (newConfidence > confidence)
 {
 confidence = newConfidence;
 candidate = tmpCodec;
 }
 
 tmpCodec = gCodecList->next;
 
 }

 if ((confidence > 0.0) && candidate)
 return candidate;
 return 0;
}

GfxImage * 
CreateRasterFromFile(BFile *file)
{
 GfxImage *newImage = NULL;
 GfxCodec *codec = 0;
 
 codec = FindImageDecoder(file);
 
    // Create an image using the codec
 if (codec)
 {
 newImage = codec->CreateImage(file);
 } else
 {
 printf(" CreateRasterImageBFile\
 no appropriate codec found\n");
 }
 
 return newImage;
}
GfxImage * CreateRasterImage(char *fname)
{
 GfxImage *newImage = 0;
 BFile *file = 0;
 record_ref aRef;
 
 get_ref_for_path(fname, &aRef);
 file = new BFile(aRef);
 
 newImage = CreateRasterFromFile(file);

 delete file;
 
 return newImage;
}

Finally, CreateRasterImage() ties everything together. Using a filename based interface is an simple matter of conversion. The BeOS can use either a posix like interface for file control, or the native BFile objects. The CreateRasterImage() function simply creates a BFile to represent the specified filename, then calls our previous function to actually create the image.

Some of the supporting functions and classes were left out for brevity, but you can access the full source for this example at ftp://ftp.be.com/pub/Samples/Rraster.tar. This is the complete source including Metrowerks' projects for the BeBox with a couple of decoders thrown in.

Ubiquitous and relatively easy support for add-ons is a basic ability of the BeOS environment. Add-ons are a well known and desired feature in the multimedia authoring market. This is an example of the re-alignment of the OS to meet the needs of today's, and hopefully tomorrow's marketplace. It is not a paradigm shift, and its value is probably worth more than $0.20.

William Adams is a Technical Evangelist at Be, Inc. He has the task of exciting and enticing the development community to create applications for the BeOS. Prior to joining Be, William worked independently at his own company Adamation, Inc. He has extensive experience with development in the NeXT environmentas well as the Taligent CommonPoint effort.