Jump to content

Photo

rb+ tutorial #4: assets.txt AKA how do import graphics and sound in rb+?

assets.txt rb+ graphics import sound import

18 replies to this topic

#1 ggn OFFLINE  

ggn

    Stargunner

  • 1,382 posts
  • Location:Athens, Greece

Posted Tue Mar 14, 2017 7:09 AM

Since this question pops up frequently, and there isn't any proper documentation for it, I decided to write a small post to explain things a bit.

Graphics
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 0011
For 8 bits/pixel it'll read 8 consecutive bits for the pixel etc. etc.

Audio
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.bmp
The 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.

Graphics:
- 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.

Audio:
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.

Packing:
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.

Rmotion:
Finally enter "Rmotion" to import a Rmotion script. This is something of an advanced topic so we'll leave that out for now.

General comments
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.


#2 saboteur OFFLINE  

saboteur

    Chopper Commander

  • 110 posts

Posted Tue Mar 14, 2017 8:00 AM

Well thought out description.

 

Any recomendations for a compliant pixel editor ?



#3 saboteur OFFLINE  

saboteur

    Chopper Commander

  • 110 posts

Posted Tue Mar 14, 2017 8:02 AM

Also, any positives or negatives to having all animation frames in one image or seperate images.

 

Sorry for the q's but I find this part of RB+ quite confusing, but utterly fascinating.



#4 ggn OFFLINE  

ggn

    Stargunner

  • Topic Starter
  • 1,382 posts
  • Location:Athens, Greece

Posted Tue Mar 14, 2017 8:08 AM

Well thought out description.
 
Any recomendations for a compliant pixel editor ?


Paint shop pro versions 8 and lower (commercial), grafx2, ProMotion NG, Gimp is a few I can think of right now


Also, any positives or negatives to having all animation frames in one image or seperate images.
 
Sorry for the q's but I find this part of RB+ quite confusing, but utterly fascinating.


AFAIK raptor expects all animation frames to be in the same file, or to be consecutive. Better go for the first option to be safe.

#5 saboteur OFFLINE  

saboteur

    Chopper Commander

  • 110 posts

Posted Tue Mar 14, 2017 8:16 AM

Ahh. never even thought of using GIMP as a pixel editor always used it for photo editing - good to know.

 

Found a tutorial for this which may be usefull to others

 

https://www.youtube....h?v=oAaoh49yf5A

 

Thanks for the good info ggn.



#6 CyranoJ ONLINE  

CyranoJ

    Quadrunner

  • 5,411 posts
  • RAPTOR in LOCAL
  • Location:Adelaide, SA

Posted Tue Mar 14, 2017 2:28 PM

Also, any positives or negatives to having all animation frames in one image or seperate images.

 

Sorry for the q's but I find this part of RB+ quite confusing, but utterly fascinating.

 

RAPTOR animation files: The frames are stored in vertical strips, in reverse order - last frame at the top, first frame at the bottom.



#7 saboteur OFFLINE  

saboteur

    Chopper Commander

  • 110 posts

Posted Thu Mar 16, 2017 9:44 AM

OK i'm starting to plan a few things out but before I get too far into a dead end - what is the jags screen resolution ?

 

I don't want to create graphics or placeholders X by Y and then find they are too large or small.

 

Cheers



#8 sh3-rg OFFLINE  

sh3-rg

    River Patroller

  • 3,392 posts
  • doge + tie = dothemath
  • Location:BOLTON, England

Posted Thu Mar 16, 2017 11:59 AM

OK i'm starting to plan a few things out but before I get too far into a dead end - what is the jags screen resolution ?

 

I don't want to create graphics or placeholders X by Y and then find they are too large or small.

 

Cheers

 

It's not fixed, but maybe it's an idea to work within the range 320x200 and 352x240ish. Some TVs overscan a little and different standards (PAL/NTSC) will also be set up to show different sized screens.

 

Those are the kinds of ranges I work with.



#9 Christos OFFLINE  

Christos

    Stargunner

  • 1,014 posts
  • Location:Thessaloniki, Greece

Posted Fri Mar 17, 2017 2:20 AM

Great read, I finally understand the existence of the clut part. However, unlike the ST/Falcon, the jaguar has chunky graphics and the palette is always the maximum. Why would we need to define a palette? And let's say I have two bmp's, a 16 colour one and 256 colour one with some colours overlapping. What would the colour assignments be then? I guess I need to get more understanding of the jaguar graphics subsystem.


Edited by Christos, Fri Mar 17, 2017 2:21 AM.


#10 ggn OFFLINE  

ggn

    Stargunner

  • Topic Starter
  • 1,382 posts
  • Location:Athens, Greece

Posted Fri Mar 17, 2017 7:25 AM



Great read, I finally understand the existence of the clut part. However, unlike the ST/Falcon, the jaguar has chunky graphics and the palette is always the maximum. Why would we need to define a palette? And let's say I have two bmp's, a 16 colour one and 256 colour one with some colours overlapping. What would the colour assignments be then? I guess I need to get more understanding of the jaguar graphics subsystem.

 

I'm not sure I get what you mean. Chunky pixels is just a way of storing them. They're not chunky because they're fat or wide or anything. It more tells that all the bitplane pixels are stored one after the other in contrast with ST/Amiga bitplanes. If you have 4bpp mode chunky you still don't have enough bits to store RGB values. So you still store the same amount of bits. In anything other than RGB16 or RGB24 you will have to use a palette again. As for your other question, you probably missed the index field in the OP post (I haven't explained it much of course, that's true). In brief, that field tells the OP where to start reading palette indices inside the palette. So you can split the palette space into 16 sub-palettes and choose from them per object.

 

Hope that makes things clearer :).


Edited by ggn, Fri Mar 17, 2017 7:26 AM.


#11 sh3-rg OFFLINE  

sh3-rg

    River Patroller

  • 3,392 posts
  • doge + tie = dothemath
  • Location:BOLTON, England

Posted Fri Mar 17, 2017 8:53 AM

Great read, I finally understand the existence of the clut part. However, unlike the ST/Falcon, the jaguar has chunky graphics and the palette is always the maximum. Why would we need to define a palette? And let's say I have two bmp's, a 16 colour one and 256 colour one with some colours overlapping. What would the colour assignments be then? I guess I need to get more understanding of the jaguar graphics subsystem.

 

You can use 16bit objects and not worry about colour palettes as I think you are suggesting, but you can also use lower bit depth objects that use the whole (8bit image, 256 colours) or a specific part of (1,2,4bit, 2, 4 or 16 colours) the CLUT if you want to save memory and bandwidth, both of which are usually at a premium.

 

Within the context of rb+, you can think of the CLUT as one large 256 colour palette* or 16 smaller palettes, you can think of these as "mini CLUTS" if it helps (I do).

 

So with your two images that you wish to use as objects, you would have to design both the 256 colour object and the 16 colour object in a way that the one did not impact on the other. Now you could either reserve 16 of the 256 colours and use, say, the first 240 colours for your 8-bit image and have a unique 16 colours for the 4-bit object. Or you could use all 256 colours in your 8-bit object and carefully design the palette so that it had 16 useful colours for your 4-bit object within one of the 16 chunks of 16 colours.

 

Here's an image that hopefully demonstrates this better than my crappy words:

 

Attached File  clutarse.png   26.71KB   1 downloads

 

So in the above examples, you can see the whole CLUT is set up with the first 15 sets of 16 colours being a rather boring gradient and the last 16 of 16 a rainbow of stark colours. The first object is 8bit, it can use any of the colours in the whole 256 range of the CLUT, but it only uses 0-239 as it's not needing those garish colours at the end.

 

The 2nd object is a 4bit (16 colour) one and is designated to use the last 16 colours (mini CLUT 15 in the range 0-15) as its source for colours.

 

The 3rd object is exactly the same as the 1st one, but also uses the remaining 16 colours for some lovely embellishments!

 

There are also examples of 2-bit and 1-bit objects. These use the first 4 or 2 colours of each mini CLUT.

 

With the above, you should also be able to see how you can drastically change the appearance of an object simply by assigning it a new mini CLUT value.

 

* (it's rare you'd want to, efficiencies over 16bit are... limited? Although Bexagon makes good use of it for example as it hammers all the colour registers every frame)


Edited by sh3-rg, Fri Mar 17, 2017 9:03 AM.


#12 Clint Thompson OFFLINE  

Clint Thompson

    River Patroller

  • 4,347 posts
  • Kiss Reality Goodbye.
  • Location:Indianapolis, Indiana

Posted Tue May 23, 2017 2:54 AM

Graphics and Sound and.... Animation

 

​I didn't have a problem animating my space ship the other day for a Cosmic Ark-like clone (actually I did, but learned that they need to be divisible by 16, the graphic sizes). Now however, I'm having a hard time getting images to sync up for this example background. This may not be ideal for general gaming but I would like to know what I'm doing wrong so I can learn. I've tried multiple different image sizes from 320x240, 352x240, 352x252 and 352x244 and now 320x200.  All results are the same and I've layered the image multiple times in GIMP and then tossed it into XNVIEW so it would export in the acceptable format. The problem is the image continues to look like it's rolling when it's not. 

 

Attached is the image I'm using (320x1200) with subsequent frames set to 5 (as seen in the code below) and I've changed various things around to see if I can get it to work but it never does. What goofy mistake am I making that is preventing this from working and also so others may learn from my very costly mistake time-wise in trying to figure out what I'm doing wrong.

 

Image:

Attached File  background.bmp   1.1MB   6 downloads

 

Object code:

 

Attached File  object2.txt   5.15KB   6 downloads

 

ROM:

Attached File  Dragonox.rom   1MB   3 downloads

 

Video:

 

BTW, thanks for these elaborate tutorials, I'm loving them!

 



#13 ggn OFFLINE  

ggn

    Stargunner

  • Topic Starter
  • 1,382 posts
  • Location:Athens, Greece

Posted Tue May 23, 2017 4:51 AM

Graphics and Sound and.... Animation
 
​I didn't have a problem animating my space ship the other day for a Cosmic Ark-like clone (actually I did, but learned that they need to be divisible by 16, the graphic sizes). Now however, I'm having a hard time getting images to sync up for this example background. This may not be ideal for general gaming but I would like to know what I'm doing wrong so I can learn. I've tried multiple different image sizes from 320x240, 352x240, 352x252 and 352x244 and now 320x200.  All results are the same and I've layered the image multiple times in GIMP and then tossed it into XNVIEW so it would export in the acceptable format. The problem is the image continues to look like it's rolling when it's not. 
 
Attached is the image I'm using (320x1200) with subsequent frames set to 5 (as seen in the code below) and I've changed various things around to see if I can get it to work but it never does. What goofy mistake am I making that is preventing this from working and also so others may learn from my very costly mistake time-wise in trying to figure out what I'm doing wrong.
 
Image:
attachicon.gifbackground.bmp
 
Object code:
 
attachicon.gifobject2.txt
 
ROM:
attachicon.gifDragonox.rom
 
Video:

 
BTW, thanks for these elaborate tutorials, I'm loving them!


Well, I tried smaller values for R_sprite_framesz and they seemed to work fine. It looks like any value above 320*2*100 gives wrong reasons.

Which points to a raptor bug. So scream out loud, make funny noises, honk etc so the library will be fixed fast (i.e. it's not up to me!)

#14 Clint Thompson OFFLINE  

Clint Thompson

    River Patroller

  • 4,347 posts
  • Kiss Reality Goodbye.
  • Location:Indianapolis, Indiana

Posted Tue May 23, 2017 5:35 AM

...I have no words.

 

(tosses computer out 2nd window)

 

Welp, there it goes. If it ever gets fixed, I'll be back. (Rb+, not my computer... I always have backups and spares after all..)

 

;-)



#15 CyranoJ ONLINE  

CyranoJ

    Quadrunner

  • 5,411 posts
  • RAPTOR in LOCAL
  • Location:Adelaide, SA

Posted Tue May 23, 2017 7:37 AM

Well, I tried smaller values for R_sprite_framesz and they seemed to work fine. It looks like any value above 320*2*100 gives wrong reasons.

Which points to a raptor bug. So scream out loud, make funny noises, honk etc so the library will be fixed fast (i.e. it's not up to me!)

 

Bug: Confirmed.

Location: Identified

Problem: Analyzed

Resolution: ......

 

While this is a simple(!) fix, the solution could potentially break many, many examples. It's best left for the next revision of RAPTOR which will bring new features (and have a requirement to break backwards compatibility in several places)



#16 ggn OFFLINE  

ggn

    Stargunner

  • Topic Starter
  • 1,382 posts
  • Location:Athens, Greece

Posted Tue May 23, 2017 9:36 AM

...I have no words.

 

(tosses computer out 2nd window)

 

Welp, there it goes. If it ever gets fixed, I'll be back. (Rb+, not my computer... I always have backups and spares after all..)

 

;-)

 

Can I offer a workaround while we wait? Change the object's gfxbase by hand. Something like:

dim current_frame as short
dim current_anim_frame as short
dim current_background_address as int
 
current_frame=0
current_anim_frame=0
current_background_address=start_of_animated_background_address
 
do
    vsync
   current_frame=current_frame+1
   if current_frame=28 then
      current_frame=0
      current_anim_frame=current_anim_frame+1
      current_background_address=current_background_address+320*200*2
      if current_anim_frame=6 then
         current_anim_frame=0
         current_background_address=start_of_animated_background_address
      endif
      rlist[1].gfxbase=current_background_address
   endif
loop

I think it's pretty straightforward but let me walk through the code real quick:

 

  1. Clint's object was changing frames every 28 frames
  2. Also there were 6 frames of background animation
  3. We keep a counter for the frames passed, if that reaches 28 then we must change the background address. Reset the frame counter too.
  4. We use another counter to know which frame to set, 0 to 5
  5. We also keep the address at another variable to avoid having to multiply (i.e. current_background_address=current_anim_frame*320*200*2)
  6. If the animation counter goes to 6 then it's time to reset it to 0, along with the background address.
  7. Finally we simply set the background address to gfxbase and loop back

Not very difficult to do I think and it will do the job! (Disclaimer - I wrote it but didn't test it at all! There might be typos or logic errors but I hope you get the idea anyway!)

 

Hope this helps you get back on track :).



#17 Gemintronic OFFLINE  

Gemintronic

    Jason S. - Lead Developer & CEO

  • 9,139 posts

Posted Tue May 23, 2017 9:45 AM

This is probably another instance of me missing information people have already posted about.  What is the best free graphics program to make rB+ compatible sprites/tiles in?  My trial of Paint Shop Pro runs out and then I'm back to square one.



#18 ggn OFFLINE  

ggn

    Stargunner

  • Topic Starter
  • 1,382 posts
  • Location:Athens, Greece

Posted Tue May 23, 2017 11:38 AM

This is probably another instance of me missing information people have already posted about.  What is the best free graphics program to make rB+ compatible sprites/tiles in?  My trial of Paint Shop Pro runs out and then I'm back to square one.

 
[EDIT] Never mind, I created a new topic for it :).

Edited by ggn, Tue May 23, 2017 12:33 PM.


#19 Zerosquare OFFLINE  

Zerosquare

    River Patroller

  • 2,677 posts
  • Location:France

Posted Wed May 24, 2017 8:04 AM

While this is a simple(!) fix, the solution could potentially break many, many examples.

Easy. Have a variable named WANT_BROKEN_BEHAVIOUR and enable the fix conditionnally :P

 

Or do it the Atari way: put a warning somewhere in the doc and never fix the problem :D





Reply to this topic



  



Also tagged with one or more of these keywords: assets.txt, rb+, graphics import, sound import

0 user(s) are browsing this forum

0 members, 0 guests, 0 anonymous users