I do plan to cover pixel formats in more detail in the OP thread so I'll make a very brief notice here. The Object Processor supports graphics of various colour depths: 1,2,4,8,16 and 24 bit, as well as the infamous CRY mode. Regardless the mode, the OP expects graphics to be in chunky format. This means that each pixel's data must be consecutive and packed one after the other. So, if we have a 4bpp object and we want its first 4 colours to be palette indices 1,8,10,3 the OP will expect to see this in RAM:
Pixel 1 2 3 4 Index 1 8 10 3 0001 1000 1010 0011For 8 bits/pixel it'll read 8 consecutive bits for the pixel etc. etc.
For audio the hardware supports 2 16-bit channels but in order to ease mixing the usual format for sound effects is 8bit signed or unsigned.
How to do it
So, to import assets in code, people more or less were required to roll their own system with its own class of features, bugs and limitations. Raptor also has an internal graphics conversion system, which is what rb+ used initially. However this required modifying the main assembly source and recompiling, so this was less than ideal for people that find assembly scary. Thus a build step in rb+ was added which tries to do all the above (and more) automatically for the user.
So in each project's folder there's a file called assets.txt that instructs the build system to import files ready for the rb+ program and convert them if required. Each time you create a new rb+ project from the command line (build.bat <projectname> new"), a sample assets.txt is copied to the project directory. Its contents are more or less the following:
' rB+ assets file. ' ' This is where we tell rB+ to load in our graphics and sounds etc. ' ' Firstly, all these lines are comments and are not useful to the build process. ' To be exact, all lines starting with the characters ";", "#", "'", "*" are considered to be comments. ' ' Each non-comment assets.txt line is considered to have 4 comma separated strings of text like the following: ' A,B,C,D ' | | | +-- Filename of the asset, relative to the project folder (i.e. assets\gfx\background.bmp) ' | | +---- Tells the build process if the file should just be imported as is or some conversion is needed beforehand. See below for details. ' | +------ Name asset which is exposed to rb+. Actually two variables are exposed to rb+: name and name_end which holds the start and end addresses of the asset. ' | Names may start with an uppercase or lowercase letter (A-Z a-z), an underscore (_), a question mark (?) or a period (.). ' +-------- This should either be ABS or ROM. This tells the build process if you want the asset to be included in RAM or ROM. ' ' Parameter C explained further: ' - This can be any text if you have some asset that you want imported in rb+ as is (for example a converted raw sample or a backdrop). For this you can put any text in C. ' - For graphics conversion you can use "gfx_clut" or "gfx_noclut" to convert a .BMP file into jaguar raw format and optionally export the paletter or not (clut=yes, noclut=no). ' This applies to 1-, 2-, 4- and 8-bit graphics only. ' For 16-bit and 24-bit graphics no clut is created (because there isn't a need for one). ' Finally for 16-bit images you have to use gfx_clut16 or gfx_noclut16. ' - For conversion to CRY mode use "gfx_cry". ' - For audio files you can use "sfx_rawXXXXX" to convert any audio file (for example .wav, .mp3, .ogg, etc) into raw format. ' You can optionally set XXXXX to be the desired sample rate, otherwise 8000Hz is used by default. ' - If you want the audio files to be compressed using u-law then use "sfx_mlawXXXX" instead (note - this requires Zerosquare's player!) ' - Rmotion scripts should be placed here, use "rmotion". ' - Finally, if you want an asset packed, append a "_pack" suffix. For example "gfx_noclut_pack". ' Note that rmotion scripts and CLUTs aren't packed for now. ' Also note that it's your responsibility to reserve RAM for unpacking as well as running powaunpack to unpack the asset. ' ' That's all, have fun! ' ' End of file.Scary? Let's break it down a bit.
First of all, all lines starting with ";", "#", "'", "*" are not taken into account. So effectively assets.txt is a blank file.
The non-comment lines should have 4 parameters, separated by commas. So, something like:
ABS,main_sprite,gfx_clut,assets\gfx\main_sprite.bmpThe first parameter tells the tool where to place the imported file. ABS means place in RAM and ROM place in ROM. Usually ABS is prefered for development work, especially if you send the resulting binary to the real machine. You don't have to burn a ROM, just upload the binary to RAM and run.
The second parameter controls the name of the asset which is exposed to rb+. For example, if your asset is a graphic, then to define it as a raptor object you will need to know the graphic's start address. Since this is a number not known at build time, traditionally we will pass a symbol name and let the build process sort it out. So this name has to be unique.
The fourth parameter is simply the filename of the asset.
The third parameter is more tricky, so it's covered last. It's the magic glue that happens in order to convert the file to a format digestable by the jaguar hardware. So let's go through the options one by one.
- For 1,2,4 and 8 bpp formats it's not enough to simply convert the image to chunky format. We also need the RGB values of the pixel indices we use, also called a "palette" or a "clut" (colour look-up table). So we enter gfx_clut as the third parameter. If for some reason we don't require the palette to be generated we can supply gfx_noclut. Note that the source image has to be in .bmp format and that the file has to be in the number of bpp that you want your object to be.
- For 16/24bpp formats there is no need for palette, there are enough bits to store RGB values directly. In this case the third parameter is gfx_clut16 or gfx_noclut16 - the result will be the same.
- If your object is in CRY mode then you need to enter gfx_cry as the third parameter. Note that the source image has to be in .bmp format.
The import program uses a program called sOx to convert the sounds to jaguar formats, so it can accept pretty much all input formats you feed it (mp3, ogg, wav etc should be fine).
- For a plain uncompressed raw file you can use sfx_rawXXXXX or sfx_raw to convert it. The short format will default to converting the sample to 8000Hz. Otherwise you can specify your own replay rate if you pass a number instead of XXXXX.
- Zerosquare's audio code also supports an additional mode, which provides some compression. You need to use sfx_mlawXXXXX to convert to this format.
This can be very handy for graphics, especially 16bit images which can take up quite some space. if you postfix your commands with pack then the asset will be packed after conversion, for example gfx_clut16_pack. There is a sample project caled "pack" that demonstrates packing and unpacking, so be sure to check it out.
Finally enter "Rmotion" to import a Rmotion script. This is something of an advanced topic so we'll leave that out for now.
As you notice, rb+ tries to do a lot of things behind your back and lower the entry level for doing things. It has its faults of course - .bmp format for input is not ideal and at some point this might be addressed by using third party libraries.
One of the most popular questions/bug reports that surface is graphic import conversion errors. It's natural because it is a confusing topic, especially since the import tool expects the bmp files to be the same amount of colours as the object you want to define. Believe it or not this is a design choice: Nobody knows how you want your graphics to look like better than the user. For example, in bitmapped objects colour 0 has to be the transparency colour. If the import tool were to do this automatically then how would it be able to pick colour 0? There's no easy way. So the import tool leaves that choice to the user. We want you to have control of this. We want you to learn to use a pixel editor that supports low bpp modes. Otherwise your imports will work out of luck. And when they don't.... "rb+ is broken!".
Edited by ggn, Tue May 23, 2017 12:58 PM.