VBXE for Beginners Tutorial Thread

[Mark2008]

5 hours ago, Geister said:

Do you combine your interests and use PL65 with VBXE?  I think the combination should make good use of the Video features of the board.  

 

I'd love to see a 1090 compatible version (plug and play) of the VBXE and think that Atari was really shorted by Atari dropping that expansion chassis.

 

Yes, I started a new thread, and put that thread in the programming section, but I do think that PL65 is the way to go.

 

So, the thread is an "open participation" ABBUC contest entry development thread - but it will be VBXE and PL65.

 

The game being ported is Doubleback, and I will be seeking contributions from anyone interested in joining, the effort.

 

I've pondering the best way to handle this - an open participation effort, where there both needs to be timely progress and the ability to accept input that may come at unknown times.

 

What I think I will do is put placeholders in - placeholder title screen, placeholder music, placeholder graphics - that way I can both make rapid progress and still al so alllow for someone to contribute music, contribute artwork and even contribute code.

 

I will even placeholder the algorthims, anyway, I'm rambling a bit, you didn't ask all that, lol    The game will be PL65 and assembler and also target VBXE.  Although it's a combination of creating an ABBUC entry - it is also a continuation of exploring VBXE capabilities.

[Mark2008]

ah, I'm just being chatty - anyway - doubleback is a game where you encircle items on a screen while avoiding running into them.

 

The "items" will all be VBXE controlled...but beyond VBXE coding, an interesting challenge is how to optimize the engine such that you can tell if an item is inside an arbitrary closed loop.

 

As for placeholder 'algorithm' - my thought is simply to do a bounding box to get a limited number of objects that could possibly be inside the closed loop.  And then from the possible items do ray casting.  

 

I could discover that none of this is important - or what often happens is another idea presents itself. Or in this case, maybe someone has already done this before and knows exactly the most optimized path - I'm open to anything really - the only goal is to make sure it is a completed game that is also a fun game.  I've never actually played doubleback and have no plans to play it. So there will be no particular adherence to the original - it's just the inspiration.

[Yaron Nir]

@Mark2008, i am interesting to dive deeper to understand better the XDL structure. 

i wonder if there is a good reference that you can refer me to. by good i mean, each line of XDL what it does and what the values i can use as parameter. from your text file (which was excellent b.t.w - good work!) i couldn't figure out a lot about the XDL

 

thanks!

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[Mark2008]

1 hour ago, Yaron Nir said:

@Mark2008, i am interesting to dive deeper to understand better the XDL structure. 

i wonder if there is a good reference that you can refer me to. by good i mean, each line of XDL what it does and what the values i can use as parameter. from your text file (which was excellent b.t.w - good work!) i couldn't figure out a lot about the XDL

 

thanks!

 

I agree - this tutorial is quite limited in discussing the XDL.  That is to say, my original effort had simply been to use the S2: driver, which sets up an XDL for the user without them having to configure an XDL at all.

 

Ultimately using the S2: driver wasn't satisfactory because I couldn't reliably load it from BW-DOS using the loading tool.  It would load manually but when scripted, it would fail.  So, a quick fix was to  implement an XDL in code.  Altirra was used to simply view that XDL that S2: driver sets up and then I poked in a matching XDL, with no changes.

 

Interestingly enough, as I got deeper into the game, an earlier XDL that I had setup with 240 lines may have been more appropriate.  Just as atari players can go off the top of the screen, so too can TI extended basic sprites.  The S2: driver maps the display area to visible lines, but an XDL that maps all lines, including overscan, may have been both simpler to write and more true to the original game.

 

OK, that's some background, now - how to understand an XDL.  The sources that have occurred to me so far are the PDF documentation which is called vbxe_en.pdf and is available from lotharek.  I must confess that I don't find it in a tutorial style, and I also don't understand it.

 

Another method to glean information is from earlier VBXE threads on atari age, and from open source VBXE projects, and other VBXE projects.  I would think of particular interest would be the mad pascal project.  I gleaned how to poke in the palette, from someone that had poked in a palette. How to set up the memory window from someone that had set up a memory window - rybags had a thread, I think.

 

The challenge with the best examples that I came across is they are almost entirely written in mads assembler, meaning that one has to both learn VBXE and Mads assembler at the same time.  And my experience was that any look into someone's mads assembler open source code will reveal macros that aren't part of the documentation.   So, one should go all in on learning mads assembler in order to freely examine the bulk of vbxe open source.  

 

But of course, the idea of a tutorial is to offer a different path from that - and that's where I'd say feel free to dive right in and ask questions - I'm sure others will be of aid, if its something I know, I'll try as well - but more expert folks are out there, I suspect.

 

 

 

[Yaron Nir]

@Stephen i sure hope could use an example. i've read the tutorial that mark has mentioned above, but unfortunately same as him, i didn't understand it (especially the part of the XDL).

does your example contain code comments and an explanation? i am seeking mostly for those.....

thanks!

 

@Mark2008 unfortunately i found the documents online not to my satisfactory. i program in MADS assembly so i can read the code posted by others but unlike your text file they don't explain step by step as you have. and i find a lot of the data missing for me to understand.

for example, i haven't seen anywhere what values and what their meaning is for XDL rows. that is a big gap.

 

btw - I have started drafting a vbxe wrapper in MADs assembly and i am basing it on the knowledge collected from your explanations and other stuff i found online that helps. once done i will share but it will take sometime for that to be completed as life takes its priorities  

 

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[Yaron Nir]

4 minutes ago, Stephen said:

I will have to work on an explanation later today after work.  While I do have commented code, it's basically just rehashing what is in the user manual.  I don't have an explanation written out for each part of the XDL.

[code]

;-----------------------------------------------------------------------------

; Xtended Display List

;-----------------------------------------------------------------------------

XDL

    ; XDLC Block 1 (87 scanlines)

    ;bit 76543210

    dta %01110010               ; XDLC Byte 1 $72 (XDLC_GMON | XDLC_MAPOFF | XDLC_RPTL | XDLC_OVADR)

    dta %00001000               ; XDLC Byte 2 $08 (XDLC_ATT)

    dta $56                     ; XDLC_RPTL (1 byte) No changes in next 86 scanlines

    dta $00,$30,$01,$40,$01     ; XDLC_OVADR (5 bytes) = OVADR (3 bytes) $013000, OVSTEP (2 bytes) = $0140

    dta %00010001,$FF           ; XDLC_OVATT (2 bytes) OV_WIDTH=01 | XDL_OV_PALETTE=01 | XDL_PF_PALETTE=00, Priority=FF

    ; XDLC Block 2 (153 scanlines)

    ;bit 76543210

    dta %01110010               ; XDLC Byte 1 $72 (XDLC_GMON | XDLC_MAPOFF | XDLC_RPTL | XDLC_OVADR)

    dta %10001000               ; XDLC Byte 2 $08 (XDLC_ATT | XDLC_END)

    dta $98                     ; XDLC_RPTL (1 byte) No changes in next 152 scanlines

    dta $00,$9E,$01,$40,$01     ; XDLC_OVADR (5 bytes) = OVADR (3 bytes) $019E00, OVSTEP (2 bytes) = $0140

    dta %00100001,$FF           ; XDLC_OVATT (2 bytes) OV_WIDTH=01 | XDL_OV_PALETTE=10 | XDL_PF_PALETTE=00, Priority=FF

XDL_Length  equ *-XDL

[/code]

thank Stephen! 

what i am looking for is to understand better each value.

for example the first value:

dta %01110010               ; XDLC Byte 1 $72 (XDLC_GMON | XDLC_MAPOFF | XDLC_RPTL | XDLC_OVADR)

 

what each value mean, what other values i can use etc..... this goes to all values in the XDL

 

 

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[Yaron Nir]

Out of curiosity i have typed .vbxe_xdl in altirra debugger:

so once i understand better the values and what do they do and what do they mean i can look at the debugger with more confident and better understanding.

 

7 minutes ago, Stephen said:

The | symbol is a binary OR.  So that 1st byte takes 4 values and stuffs them into the single byte.

XDLC_GMON = Enable graphics mode (bit #0 = 0, bit #1 = 1, bit #2 = 0) Only one of those 3 bits can be set

XDLC_MAPOFF = Disable colour attributes (bit #3 = 0, bit #4 = 1) Only one of those 2 bits can be set

XDLC_RPTL = Bit #5 = 1, this tells the XDL to make no changes for the following # of scanlines.  This # is a byte that comes after the 1st 2 bytes

XDLC_OVADR = Bit #6 = 1, this tells the XDL where to get the screen RAM.  This is 5 bytes

XDLC_OVSCRL = Bit #7 = 0, this tells the XDL to not use scrolling

This is great!  

 

graphics mode 0,1,2 - what does this mean ? 

other than that the other values make sense

 

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[Yaron Nir]

1 minute ago, Stephen said:

Bits 0, 1, 2 determine what mode the current line will be (only one bit can be set)

If bit 0 = 1, set Text mode

If bit 1 = 1, set Graphics mode

If bit 2 = 1, disable the VBXE overlay for this line

 

Byte 2 has to be decoded in order to determine which graphics mode to use (lo, medium or high res).

If bit 4 = 1, use Hi-Res (640 pixels per line)

If bit 5 = 1, ise Lo-res (160 pixels per line)

If Both bits 4 and 5 are 0, use the standard Med-res (320 pixels per line)

great!

that is the type of explanation i was looking for!

thanks @Stephen

[Xuel]

FYI, looks like the palette doesn't get loaded properly if the VBXE is at $D700. Works fine at $D600.

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[Yaron Nir]

4 hours ago, Stephen said:

Would you like it if I create a separate thread for the XDL example?  I can ask a mod to move that content and create a new thread for you, and it may even help with searching for info, with the separate topics.

let's do that. that's a good idea and can help a lot to others. i would however make it a broader thread and cover entire VBXE.

for example, @Mark2008 in his text file set the step by step to set up the VBXE.

we can break down each step and write our own comments and documentation and elaborate as much as possible.

what do you guys think?

[rayr]

9 hours ago, Yaron Nir said:

let's do that. that's a good idea and can help a lot to others. i would however make it a broader thread and cover entire VBXE.

for example, @Mark2008 in his text file set the step by step to set up the VBXE.

we can break down each step and write our own comments and documentation and elaborate as much as possible.

what do you guys think?

Sounds good to me. I'm just starting to use my VBXE. It's a great addition to my Atari and I would love to utilize it more.

[_The Doctor__]

I'm just glad Stephen stuck his neck out and shared his code and insights, this is exactly what is needed in the Atari world for not only base machines but upgraded Atari's as well.

Normally we get a picture, gif, or video of progress with some quick blurb a fresh new Atarian couldn't hope to know much about. In this instance we see the journey that most folks not only can understand but benefit from.

 

Thank you @Stephen !!

and thank you for the nice images too!

[Yaron Nir]

@Stephen & @Mark2008

i have a question in regards implementing the XDL.

 

in a header file i found , there were the following attributes defined:

;-------------------------------------------
; XDLC 
XDLC_TMON       equ     1 		; Enable Overlay Text Mode
XDLC_GMON       equ     2  		; Enable Overlay Graphic Mode
XDLC_OVOFF      equ     4   	; Disable overlay
XDLC_MAPON      equ     8  		; Enable color attributes
XDLC_MAPOFF     equ     0x10    ; Disable color attributes
XDLC_RPTL       equ     0x20  	; No changes in next x lines (repeat previous scanline), number of scanline "x" 1 byte
XDLC_OVADR      equ     0x40    ; Set the address and step of Overlay display memory 5 bytes (3 byte address and 2 bytes step), little endian
XDLC_OVSCRL     equ     0x80  	; Set scrolling values for text mode Two bytes 1. hscroll 2. vscroll
XDLC_CHBASE     equ     0x100  	; Set vbxe character base , 1 additional byte = font address
XDLC_MAPADR     equ     0x200  	; set the address and step of the colour attribute map,  5 bytes (3 byte address and 2 bytes step), little endian
XDLC_MAPPAR     equ     0x400   ; set scrolling values, width and height of a field in the colour attribute map Four bytes total:1 byte hscroll 1 byte vscroll 1 byte width 1 byte height
XDLC_OVATT      equ     0x800   ; Two bytes: 1. Overlay/map width + pallete change (0 means narrow overlay, don't know about other values) 2. main priority (higher number means higher priority)
XDLC_ATT        equ     0x800  	; Same as XDLC_OVATT
XDLC_HR         equ     0x1000  ; Enable the hires pixel mode (only when XDLC_GMON=1) Hires is 640 pixels wide 
XDLC_LR         equ     0x2000  ; Enable the low resolution mode sets 160 pixel mode							
XDLC_END        equ     0x8000  ; XDL end marker
;-------------------------------------------

this are the attributes that the first data of the XDL should contain with an OR operator.

 

So I have defined the following:

XDLC
    dta (XDLC_GMON | XDLC_MAPOFF | XDLC_RPTL | XDLC_END)
 

This means i am using graphics mode (not character mode), i am disabling the color attributes (MAPOFF), i choose to repeat this definition to # of scanlines , and i end the XDL

 

now, as far as i understand i need to set the attributes parameters in a certain order. here is where i need some help.

 

so for the graphics mode i want to use low res (160 pixels) 

for repeat lines i want to use 192 scanlines (entire screen should be the same)

so, i need help with the next dta statement to reflect the above.

also, do i need to configure other paramters? screen memory address? other?

 

my follow up question would be, once the XDLC label is ready, how do i enable it? 

 

 

 

 

 

 

[Mark2008]

@Yaron Nir

 

edit: nevermind....skip to the end....lol

 

I personally don't know MADS Assembler, but the S2 driver can set to low res with 192 lines and Altirra will reveal the XDL.

And I would follow that path, to get a working example of a 192 line lowres screen.

 

And I'll just type this out for others that may find the thread.

 

 

in the Mad Pascal download:

 

Mad-Pascal-1.6.6\samples\a8\graph_vbxe_s2\doc

 

Documentation for the VBXE "S:" display driver

 

2: pixel mode 160x192/256 colors (lowres). This is like GR.15 in 256 colors.

 

So, in basic

 

Line 10 in the first post of this thread I used "3" for stdres.

But change it to "2" for lowres.

You have to have S_VBXE.SYS already loaded and then:

 

10 OPEN #6,12,2,"S2:"
20 COLOR 128:PLOT 30,30:DRAWTO 150,150
30 GOTO 30

 

Now, you can go into Altirra and dump out the XDL created.

 

Once you have the program running go to the Altirra debugger

 

Debug->Enable Debugger

 

Then I hit Step Into once,  otherwise I cannot type into the console.

 

.help to show commands

.vbxe_xdl to show the xdl

Quote

7E130: 74 0F      ; mode off
                  ; map_off
  17              ; repeat      24
  00 00 00 A0 00  ; load_ovl    $00000, $0A0
  F8              ; load_chbase $7C000
  00 00 00 28 00  ; load_map    $00000, $028
  00 00 07 07     ; map_attr    0, 0, 8x8
  11 80           ; ovatt ovwidth=normal, ovpal=1, pfpal=0, pri=$80
7E144: 22 A0      ; mode lr
  BF              ; repeat      192
; end

That's the XDL I would use for lowres.

 

I did a similar strategy to get stdres when I did the runway game.

 

 

edit; oh nevermind, i probably need to read the thread first,  so many cool post, I just haven' thad a chance to read them.  lol

 

 

Edited January 11, 2023 by Mark2008

[+Stephen]

Moved to https://forums.atariage.com/topic/346498-vbxe-tutorial-the-xdl/

[Mark2008]

2 minutes ago, Stephen said:

Definitely need to separate this into 2 threads.  The S2 driver is nice for getting quick and dirty things going.  But it's not going to help in a lot of cases.  If you want custom screens, split modes, more than 1 palette per screen, more than 192 lines per screen, etc.

 

I will answer Yaron's question in the new thread I am going to start for XDL setup, then I will go back and edit out these posts from this thread, and finally ask a mod to delete what will become my empty posts.

 

@Yaron Nir - I will do my best to get this typed up tonight.

Absolutely agree.

 

My point is if someone needs lowres driver with 192 lines, then they have one immediatley to look at, no waiting.

I just find it beneficial to have a problem already solved.

 

BUt of course - I agree that when doing more complex things, it won't provide any example, which is why I'm keen to read your other explanations.

 

I edited my post later to say that I hadn't read the whole thread - my bad.

 

 

[+Stephen]

1 minute ago, Mark2008 said:

Absolutely agree.

 

My point is if someone needs lowres driver with 192 lines, then they have one immediatley to look at, no waiting.

I just find it beneficial to have a problem already solved.

 

BUt of course - I agree that when doing more complex things, it won't provide any example, which is why I'm keen to read your other explanations.

 

I edited my post later to say that I hadn't read the whole thread - my bad.

 

 

No worries.  The more info the better!  The more code for this great device, the better.  It's been released and in the wild for far too long, maybe we can spur some serious interest in it.