This section details the creation of a translator. If you only need to use the Translation Kit, you may safely skip this section. Otherwise, please read through the section overview of the BTranslatorRoster class before continuing.
When an application requests the conversion of a stream from one format to another via BTranslatorRoster, the Translation Kit scans through its list of translators to determine the one best suited for translating the stream. Each translator is an add-on that exports several symbols to help BTranslatorRoster make its decision. The prototypes for these symbols may be found in <be/translation/TranslatorAddOn.h>. Once you have written the required functions and data, creating the add-on involves simply including <be/translation/TranslatorAddOn.h> and compiling with -export pragma to export the appropriate symbols. A summary of the exports follows:
| Symbol | Required? | Description |
|---|---|---|
| GetConfigMessage() | no | save current configuration in a BMessage |
| Identify() | yes | identify data in a BPositionIO |
| inputFormats | no | list of supported input formats |
| MakeConfig() | no | create a view for user-configuration of translator |
| outputFormats | no | list of supported output formats |
| Translate() | yes | translate data from one format to another |
| translatorInfo | yes | long description of translator |
| translatorName | yes | short name of translator |
| translatorVersion | yes | translator version number |
status_t GetConfigMessage(BMessage *ioExtension)
This function stores the current configuration in the ioExtension in such a manner that it may be flattened, unflattened, and then passed to Translate() as an ioExtension.
This is an optional function.
status_t Identify(BPositionIO *inSource, const translation_format *inFormat,
BMessage *ioExtension, translator_info *outInfo, uint32 outType)
If the translator understands how to convert the data contained in inSource to media type outType, it fills outInfo with details about the input format and return B_OK. If it doesn't know how to translate the data, it returns B_NO_TRANSLATOR.
The quality and capability fields in outInfo are used by the Translation Kit in selecting the best suited translator for a given translation, so it is best to be conservative in choosing these values.
If the media format doesn't have a type code in <be/support/TypeConstants.h> (as will most likely be the case), choose a reasonable value. For example, the Targa handler included with the BeOS distribution uses the type code 'TGA '.
The translator need not fill in the translator field in outInfo; BTranslatorRoster fills in this value for you.
Remember that inSource may be arriving from any source, including a live network feed. It's therefore best to steer clear of calls such as BPositionIO::Size() which force all the data out of the stream. Similarly, it is good practice to read only as much of the stream as you need.
inFormat, if it is not NULL, is provided as a hint to the format of the data in inSource. Since it is only a hint, the data may very well be in some other format.
ioExtension, if it is not NULL, contains additional information for the add-on. It is described at length in the section in BTranslatorRoster titled "Configuration".
outType may be zero, in which case any output format is acceptable.
This is a required function.
translation_format inputFormats[];
translation_format outputFormats[];
These arrays tell BTranslatorRoster which formats the add-on supports. If they are not exported by the translator, the add-on's Identify() will be called each time an application requests a translation. Each array ends in an empty translation_format structure, so a typical inputFormats would look like:
translation_format inputFormats[] = {
{ 'TGA ', B_TRANSLATOR_BITMAP, 0.6, 0.5, "image/targa",
"Targa bitmap format" },
{ B_TRANSLATOR_BITMAP, B_TRANSLATOR_BITMAP, 0.4, 0.6, "image/x-be-bitmap",
"Be Bitmap format" },
{ 0, 0, 0, 0, 0, 0 }
};
and similarly for outputFormats.
These are optional data.
status_t MakeConfig(BMessage *ioExtension, BView **outView, BRect *outExtent)
This function creates a new BView through which the user configures the add-on. For example, it could be used to control the degree of image compression used or the video frame rate. The bounds of the view are returned in outExtent, although it can be resized at will by an external source. Changes to the configuration take effect immediately, although translations should be carried out with the same parameters throughout.
This is an optional function.
status_t Translate(BPositionIO *inSource, const translator_info *inInfo,
BMessage *ioExtension, uint32 outType,
BPositionIO *outDestination)
The translator translates data from inSource to format outType, writing the output to outDestination. outType may be zero, in which case it is assumed to be the default format type for the media group. As in Identify(), inInfo serves as a hint to the format of the data in inSource. ioExtension fills its usual role as a container of configuration information. The function returns B_OK if it's able to convert the data successfully. If it's unable to do so, it returns either B_NO_TRANSLATOR or an error value as appropriate.
This is a required function.
char translatorInfo[];
char translatorName[];
int32 translatorVersion;
translatorName is a C string giving the short name of the translator, i.e. "aiff translator". translatorInfo is a C string giving a long description of the translator, i.e. "aiff translator by the Pie Man (pie@the.man)". translatorVersion gives a version number for the translator. For example, a translatorVersion of 314 is interpreted as version 3.14.
These are required data.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified December 26, 1997.