vbxe VBXE Tutorial - The XDL

[+Stephen]

Here I will do my best to document the XDL (eXtended Display List) of the VBXE.  My code examples will be for the MADS assembler.  This information is provided for people that want to directly tickle the hardware, old-school style.  There is a VERY nice, well documented, feature rich VBXE driver for Sparta DOS X.  I used it and in a few hours with never coding for VBXE, had a working BMP viewer in Turbo BASIC XL.  This tutorial will not cover that, however.  Here I will help document what I have been doing the last few months.  I am learning MADS while I am learning the VBXE so please don't consider this definitive in scope or in any way expert level.

 

All VBXE labels and documentation has come directly from the VBXE Programmer's manual, English edition, Copyright © 2013 by T.Piórek.

 

Thanks to:

• @Yaron Nir for making me start this thread and make sure I keep coding regularly, by posting questions.
• @Mark2008 for getting the ball started with his VBXE for Beginners Tutorial Thread and game.
• Everyone involved in the VBXE hardware, existing software, and documentation.
• phaeron for the wonderful Altirra emulator which provides fantastic VBXE emulation with great debugging abilities.
   

[+Stephen]

VBXE Ram Usage (and how to access)

The first thing I like to do when starting a new project is consider the RAM layout.  The VBXE provides 512kB of RAM (when not using the Rambo core, then you get 256kB for VBXE plus 256kB for the Atari).  This sounds like a very large amount, but keep in mind that a worst case scenario is a single graphics screen taking up 78kB (336 bytes per line, 240 scanlines).  A small amount of ram is also needed to hold the XDL(s) and if you are using the Blitter, each BCB (Blitter Command Block) is 22 bytes.

 

The VBXE RAM is freely available to use, for any purpose, with just one caveat (that I know of) - Font data must be aligned on a 2kB boundary ($0800).  Screen RAM may start anywhere.  Unlike the ANTIC, there is no limit on the amount of data that can be read for any XDL.  A “line” may be up to 4096 ($1000) bytes.

Example:

; VBXE RAM Usage
; MEMAC_A is set to $3000, with a 4kB window
; Bank 00 - XDL & BCBs
; $000000 to $0000FF    Reserved for XDL(s)
; $000100 to $000FFF    Reserved for BCBs (enough space for 182 unique BCBs)

; Bank $01 to $12 - Sprite Sheet (256 * 288 image, 16 * 16 sprite, 16 frames per, row based)
; $001000 to $012FFF    Sprite Sheet

; Bank $13 to $25 - Screen RAM
; $013000 to $025BFF    Screen RAM (320 * 240)
; $025C00 to $025FFF    Free space

; Bank $26 to ?? - Buffers
; $026000 to $???FFF    Restore buffers

; Banks $7C to $7F (Last 4 banks of VBXE RAM)
; $7C0000 to $7FFFFF    Reserved for SDX S_VBXE.SYS Driver

 

Now that there is a plan, the code will become easier to organize.  VBXE RAM must be accessed via a “window”.  This topic will be covered later, this will be a very brief overview.  If using MEMAC-A, the size of the window as well as the location is user configurable.  MEMAC-B provides a fixed 16kB window fixed at $4000-$7FFF.  Because this can conflict with certain extended RAM configurations, I recommend using MEMAC-A.  The window must start on a $1000 boundary, and can be one of 4 sizes: 4kB, 8kB, 16kB, 32kB.  It is configured via 2 registers MEMMAC_CONTROL (MEMC) and MEMAC_BANK_SEL (MEMS).

 

MEMC (VBXE_MA_CTL) Register is used as follows:

Bits 7-4 set the base address

Bit 3 - set to 1 to enable CPU access to the VBXE RAM

Bit 2 - set to 1 to enable ANTIC access to the VBXE RAM

Bite 1-0 determine the window size

• 00 = 4kB
• 01 = 8kB
• 10 = 16kB
• 11 = 32B

 

MEMS (VBXE_MA_BSEL) Register is used as follows:

Bit 7 - set to 1 for MEMAC GLOBAL ENABLE (turn on the VBXE window)

Bits 6-3 determine the bank #0-F for 32kB window

Bits 6-2 determine the bank #0-1F for 16kB window

Bits 6-1 determine the bank #0-3F for 8kB window

Bits 6-0 determine the bank #0-7F for 4kB window

 

    lda #$38                    ; Set the base address of MEMA window to $3000 (and not collide with SpartaDosX), size to 4k and accesible only by CPU
    vbsta VBXE_MA_CTL

    lda #$80                    ; Prepare to copy data into VBXE address space
    vbsta VBXE_MA_BSEL          ; Bank 0, bit 7 set = MEMAC GLOBAL ENABLE

 

Code comments will suffice.

VBXE_MA_CTL   $38 is 00111000 (Bank 3, CPU Only, 4kB Window)

VBXE_MA_BSEL $80 is 10000000 (Global Enable, write to bank 0)

 

This means, that writing to $3000 “passes through” to VBXE $000000, $3100 will write to VBXE $0000100, etc.  Since the window size if 4kB, only $3000 to $3FFF will write (or read) to VBXE RAM.

[+Stephen]

How to setup the VBXE to use the XDL

Now that we know how to access VBXE RAM we need to do two things.  Load the XDL into the VBXE RAM, and tell the VBXE where to find the XDL.  The latter is analogous to setting the ANTIC registers SDLSTL.  From here on out, when referring to VBXE RAM, it will be noted Altirra style - that is V:$######.

 

;-----------------------------------------------------------------------------
; Copy the XDL into VBXE Memory $000000 (note this can only copy $FF bytes)
;-----------------------------------------------------------------------------
    ldx #XDL_Length
    ldy #0
Main_l1 lda XDL,y
    sta VBXE_WINDOW,y           ; We're in bank 0 so offset accordingly
    iny
    dex
    bne Main_l1

 

VBXE_WINDOW has been set to $3000, and the MEMS register is set to bank 0, therefore the XDL will be copied to V:$000000.  The following code will tell the VBXE where to find the XDL.

 

;-----------------------------------------------------------------------------
; Point the VBXE to the XDL at $000000
;-----------------------------------------------------------------------------
    lda #0
    vbsta VBXE_XDL_ADR0
    vbsta VBXE_XDL_ADR1
    vbsta VBXE_XDL_ADR2

 

The next section will have better examples of 24-bit addressing and a small talk about endianness. 

[+Stephen]

An overview of the XDL and its various features

An XDL is analogous to the ANTIC’s Display List.  It is a series of instructions that describe the screen, line by line.  It determines the mode (text or graphics) and what features are in use for each line.  As with a standard ANTIC Display List, the screen may be anywhere from 1 to 240 lines.

 

The XDL consists of a mandatory 2-byte XDLC followed by 0 through 20 bytes of additional data.  The more features that are used, the more additional data is required.  Any time a new mode is desired, an XDLC is used.  In simplest form, a single XDL can be used with the repeat command to create an entire screen.  In the most complex case, 240 XDLCs can be present, with every scanline being different.

 

Binary notation will be used for the 2 XDLC bytes because each bit has a different meaning.  The | symbol is a binary OR.  When determining which features to use, each subset will be ORed (added) together to determine the final value for that byte.

 

XDLC Byte 1 sets up 5 features.  If a particular feature is set, then the XDL will contain additional data describing it.  This can be an address to load data, or values to apply.

Bit 0 - XDLC_TMON : enable Overlay Text Mode

Bit 1 - XDLC_GMON : enable Overlay Graphics Mode

Bit 2 - XDLC_OVOFF : disable Overlay

              Only 1 bit may be set else the Overlay will be disabled

Bit 3 - XDLC_MAPON : Enable Colour Attributes

Bit 4 - XDLC_MAPOFF :Disable Colour Attributes

              Only 1 bit may be set else the Attributes will be disabled

Bit 5 - XDLC_RPTL : No changes will occur for the next # of scanlines (if repeat = 31, then 32 lines will be displayed)

Bit 6 - XDLC_OVADR : If this bit is set, 5 bytes will be used to determine the VRAM address and step

Bit 7 - XDLC_OVSCRL : If this bit is set, 2 bytes will be used to set fine scroll values for Text mode

 

XDLC Byte 2 sets up 7 features

Bit 0 - XDLC_CHBASE : If set, 1 byte will be used to point to the font (256 characters 8pxX8px , 2kB font) address

Bit 1 - XDLC_MAPADR : If set, 5 bytes will be used to determine the Colour Attribute Map address and step

Bit 2 - XDLC_MAPPAR : If set, 4 bytes will be used to set scrolling values, width, and height of a field in the Colour Attribute Map

Bit 3 - XDLC_ATT : If set, 2 bytes will be used to set display size and Overlay priority with ANTIC

Bit 4 - XDLC_HR : If set, enable the Hi-Res pixel mode (640 pixels represented by 320 bytes)

Bit 5 - XDLC_LR : If set, enable the Lo-Res pixel mode (160 pixels represented by 160 bytes)

Bit 6 - Reserved (unused)

Bit 7 - XDLC_END : If set, marks the last block in the XDL.  Processing is done.  This is analogous to the JMP and wait for VBLANK instruction that all ANTIC Display Lists must end with

[+Stephen]

Sample XDLs

Here we have a split screen graphics mode screen.  Top is 320*87@256 colours of palette 1.  Bottom is 256*153@256 colours of palette 2.

;-----------------------------------------------------------------------------
; 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,$00,$01		; XDLC_OVADR (5 bytes) = OVADR (3 bytes) $019E00, OVSTEP (2 bytes) = $0100
	dta %00100000,$FF			; XDLC_OVATT (2 bytes) OV_WIDTH=00 | XDL_OV_PALETTE=10 | XDL_PF_PALETTE=00, Priority=FF 
XDL_Length	equ *-XDL

 

This is an 80*25 text screen, using palette 1.  It has a top and bottom border of 20 lines, giving a 240 line tall display, but a visible area of 200 lines, centered.

;-----------------------------------------------------------------------------
; Xtended Display List
;-----------------------------------------------------------------------------
XDL
	; XDLC Block 1
	dta %00100100				; XDLC Byte 1 (XDLC_OVOFF + XDLC_RPTL)
	dta %00000000				; XDLC Byte 2
	dta $13						; XDLC_RPTL Repeat 20 lines

	; XDLC Block 2
	dta %01100001				; XDLC Byte 1 (XDLC_TMON + XDLC_RPTL + XDLC_OVADR)
	dta %00001001				; XDLC Byte 2 (XDLC_CHBASE + XDLC_ATT)
	dta $C7						; XDLC_RPTL Repeat 200 lines (25 text rows)
	dta $00,$40,$00,$A0,$00		; XDLC_OVADR OVADR = $004000, OVSTEP = $00A0
	dta %00000010				; XDLC_CHBASE = $001000
	dta %00010001				; XDLC_ATT Byte 1 (PF Palette 0, OV Palette 1, OV_WIDTH = normal)
	dta %11111111				; XDLC_ATT Byte 2 (Overlay has priority over everything)

	; XDLC Block 3
	dta %00100100				; XDLC Byte 1 (XDLC_OVOFF + XDLC_RPTL)3
	dta %10000000				; XDLC Byte 2 (End of XDL, wait for VSYNC)
	dta $13						; XDLC_RPTL Repeat 20 lines

 

[+Stephen]

Skeleton code for a simple "Hello World" will eventually be provided

 

[+Stephen]

--

[+Stephen]

COPIED POST #2

Continuing from earlier, here is documentation from my example code of the 2nd byte of the XDLC (XDL Control Word).

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

 

This is about as simple as byte#2 can get, as all but one "feature" goes unused.  Only bit #3 is set.  This tells the VBXE to expect 2 additional bytes of data which will describe the overlay width & the attributes map (byte 1) and the priority (byte 2).

 

From earlier:

After these 1st 2 bytes, optional additional data will be specified, in this order:

- XDLC_RPTL (1 byte)

- XDLC_OVADR (5 bytes)

- XDLC_OVSCRL (2 bytes)

- XDLC_CHBASE (1 byte)

- XDLC_MAPADR (5 bytes)

- XDLC_MAPPAR (4 bytes)

- XDLC_OVATT (2 bytes)

 

; 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

 

Now hopefully this will all make sense.

dta $56 is the single byte XDLC_RPTL.  It tells the VBXE to make no changes for the next 86 (decimal) lines.  Therefore, we will have 87 (decimal) lines of 320 pixel graphics using palette #1

 

The next 5 bytes are the XDLC_OVADR (Overlay Address).

The address of the Overlay display memory is a 19-bit value, and we use little-endian (Byte 3, Byte 2, Byte 1 as we read it, is stored as Byte 1, Byte 2, Byte 3).

Byte #1 - ovadr bits 7:0

Byte #2 - ovadr bits 15:8

Byte #3 - ovadr bits 18:16

Therefore, $00,$30,$01 means the display RAM is at VBXE location $013000

The next 2 bytes determine the step parameter (an important concept that is repeated in the blitter).  This is how many bytes to add to get to the next line in VRAM.

The step may be a value from 0 to 4095.  Keep in mind while it makes sense to store data contiguously, it does not have to be that way.

Byte #4 - ovstep  7:0

Byte #5 - ovstep  15:8

Therefore, $40,$01 means that after each 320 bytes of data are displayed, the VRAM pointer will add $0140 (320 decimal) to fetch the next line of data

 

Because I am not using text mode and I have not enabled XDLC_MAPADR or XDLC_MAPPAR, the final chunk of this 1st XDL is the 2 byte XDLC_OVATT

Byte 1 holds 3 pieces of info: XDL PF Palette (bits 7:6), XDL OV PALETTE (bits 5:4), OV_WIDTH (bits 1:0)

  00 - PF uses Palette #0 (if ANTIC was visible, it would have standard Atari palette)

  01 - VBXE Overlay uses Palette #1

  01 - OV_WIDTH is standard (320 pixels)

Byte 2 sets the Main priority.  $FF is the default value and specifies that the VBXE overlay has priority over all ANTIC generated colours.

 

Because bit 7 of Byte 2 of the XDLC was not set, this tells the VBXE that it needs to grab another 2 byte XDLC (and any optional data).  To indicate the end of an XDL, set this bit to 1.

; 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

 

The 2nd is nearly identical except it uses Overlay Palette #2, repeats for 152 (decimal) scanlines (remember, this means 153 in total), and has the XDLC_END bit set.

[+Stephen]

--

[Hrivis]

Wow, yes yes. Last night I started to do some sprites of nes game conversion to have somethink to start and have to understand, how to do some animation of sprites. I am interesten in VBXE so this will be my favorite thread, I believe. Thank you for sharing. 

Edited January 13, 2023 by Hrivis

[Yaron Nir]

excellent work @Stephen!
 

I am summarizing my takes from your post and also have some follow-up questions (inline below):

1. The VBXE memory size is 512KB.

    1.1. The VBXE memory address space is between $000000 and $7FFFFF

    1.2. The VBXE memory address is being access via banks. 

    1.3. The size of the bank is defined by dividing 512 with the size we choose for the VBXE window. for example, if we choose

           the 4K size then each bank will be 512/4 = 128. If we choose the 8K size each bank will be 512/8 = 64.

2. When planning VBXE memory layout, you should always design the memory addresses space for the following VBXE

    components:

    2.1. XDL - The extended display list. recommended to be placed in the first bank starting at memory $000000 which is

                     bank0

         2.1.1. As the XDL can be of any size (with the limit of 4K/$1000, It is safe to save size of 256 bytes ($FF) for it and that

                   should be enough. XDL can be anywhere from few bytes to 5.2KB (22*240). for most simple use cases a page of

                   RAM ($100) will suffice for the XDL.

 

    2.2. Blitter - (what is the blitter? what is it used for? how is it used ?)

         2.2.1. The blitter size is reserved for blitter command blocks (bcb). each block is 22bytes. (how to use the bcb?) 

         2.2.2. The bcb size can be in bank0 from $000100 to $000FFF  

    2.3. Sprite sheet - normally width x height size with several frames (for example 5 frames with the size of 12x40) 

         2.3.1. The sprite sheet can start at VBXE address space $001000

         2.3.2. The size of the sprite sheet can vary as it depends on the frame size and number of frames. it can be over several

                   banks

    2.4. Screen ram - the screen memory address space

         2.4.1. for screen resolution 320x240 you should  reserve 13 banks (320x240=76,800). normally, you should reserve only

                   what you'll be using. reserve means accessible via read/write.      

    2.5. Buffers - used for any RAM storage.

3. VBXE ram must be accessed via a "window". there is no other method. only through that window. 
    You can access the "window" using either MEMAC-A or MEMAC-B.

    3.1. MEMAC-A means that the size of that "window" can be configured both size and memory address space.

         3.1.1. The window must start on a $1000 boundary, and can be one of 4 sizes: 4kB, 8kB, 16kB, 32kB.

         3.1.2. The window is configured via 2 registers MEMMAC_CONTROL (MEMC) and MEMAC_BANK_SEL (MEMS).

    3.2. MEMAC-B means that the size of that "window" is fixed 16KB and is at locations $4000-7FFF

         3.2.1. Since this address space can overlap with other RAM use, it is more recommended to use MEMAC-A.

4. MEMAC-A, To configure the MEMC (memory control), you should set the following bits:

    4.1. bit 0 and bit 1 - Determine the window size (00=4K, 01=8K, 10=16K, 11=32K)

    4.2. bit 2 - Enable/Disable ANTIC access to the VBXE RAM (what does this mean?)

    4.3. bit 3 - Enable/Disable CPU access to the VBXE RAM (what does this mean?)

    4.4. bit 4,5,6,7 - 4 bytes that points to the bank that holds the window address space. 

    4.5. example of the MEMC byte set: 

           00111000 - $38
                      00 - Window size 4k
                        0 - Disable ANTIC access
                        1 - Enable CPU access,   

                  0011 - Bank 3  address $3000

5. MEMAC-A, To configure the MEMS (bank selection), you should set the following bits.

    5.1. bits 0-6  - selection for 4K (0-7F), 8K (0-3F), 16K (0-1F), 32K (0-F)

    5.2. bit 7 - Enable/Disable the VBXE window

    5.3. example of the MEMS byte set:

           10000000 - $80 
            0000000 - 4K , bank 0 

           1- enable the VBXE window

 

i hope i got most of it correctly. it is still not 100% clear to me, but i did understand most of it.

maybe when you answer my inline questions if will complete my understanding gap.

 

thanks again

 

Edited January 16, 2023 by Yaron Nir

[+Stephen]

8 hours ago, Yaron Nir said:

excellent work @Stephen!
 

I am summarizing my takes from your post and also have some follow-up questions (inline below):

1. The VBXE memory size is 512KB.

    1.1. The VBXE memory address space is between $000000 and $7FFFFF

    1.2. The VBXE memory address is being access via banks. each bank is 4K size ($1000)

Only in this specific example is the window 4kB.  The window can be 4, 8, 16, 32 kB in size but it must always be aligned to $1000.

2. When planning VBXE memory layout, you should always design the memory addresses space for the following VBXE components:

    2.1. XDL - The extended display list. recommended to be placed in the first bank starting at memory $000000 which is bank0

         2.1.1. As the XDL can be of any size (with the limit of 4K/$1000, It is safe to save size of 256 bytes ($FF) for it and that should be enough

Depending on complexity and changes, an XDL can be anywhere from several bytes to 5.2kB (22 * 240).  Before starting a project, it is imperative you know the display requirements, and what features will be in use.  For MOST simple use cases, a page of RAM will suffice for the XDL.

    2.2. Blitter - (what is the blitter? what is it used for? how is it used ?)

         2.2.1. The blitter size is reserved for blitter command blocks (bcb). each block is 22bytes. (how to use the bcb?) 

         2.2.2. The bcb size can be in bank0 from $000100 to $000FFF

The Blitter is the most advanced feature of the VBXE.  Won't be covered here.  Simply - it's a super fast memory transfer unit.  Think of it as the sprite engine.

    2.3. Sprite sheet - normally width x height size with several frames (for example 5 frames with the size of 12x40) 

         2.3.1. The sprite sheet can start at VBXE address space $001000

         2.3.2. The size of the sprite sheet can vary as it depends on the frame size and number of frames. it can be over several banks

    2.4. Screen ram - the screen memory address space

         2.4.1. for screen resolution 320x240 (should we always reserve the highest screen resolution here?) reserve 13 banks (320x240=76,800)

Only reserve what  you'll be using.  If you're doing a text screen, then the VRAM will only be 4,000 bytes (80X25 * 2 bytes per - character, colour).  Keep in mind - RAM is never "reserved".  Any location can be read / written.  When I say "reserved", I mean I am cognizant of its usage, and will handle read/write access accordingly.

    2.5. Buffers - not sure what are these used for and how?

A buffer is any memory location (or range) that is used for temporary storage.

    2.6. SDX S_VBXE.sys - not sure what this is and how it is used? 

SDX driver, can be used via BASIC or for coding SDX apps.  Irrelevant for this tutorial.

    Note - I didn't find anywhere memory space for fonts. are there any other components which are not listed that i have missed?

If you don't want a nonstandard font, no RAM is needed.  If you want to use a text mode, a custom font takes 2kB (256 characters).  keep in mind - this specific example is using graphics mode.

3. VBXE ram must be accessed via a "window" (why? can VBXE be used without this window?).

No.  There is only one bus on the Atari.  All memory is on this shared bus.  The VBXE is an add-on, so it is new hardware sharing the old bus.  The only way to communicate with this hardware is to use the MEMAC window.
    You can access the "window" using either MEMAC-A or MEMAC-B.

    3.1. MEMAC-A (memory access A?) means that the size of that "window" can be configured both size and memory address space.

         3.1.1. The window must start on a $1000 boundary, and can be one of 4 sizes: 4kB, 8kB, 16kB, 32kB.

         3.1.2. The window is configured via 2 registers MEMMAC_CONTROL (MEMC) (or is it VBXE_MA_CTL?) and MEMAC_BANK_SEL (MEMS).

    3.2. MEMAC-B (memory access B?) means that the size of that "window" is fixed 16KB and is at locations $4000-7FFF

         3.2.1. Since this address space can overlap with other RAM use, it is more recommended to use MEMAC-A.

4. MEMAC-A, To configure the MEMC (memory control), you should set the following bits:

    4.1. bit 0 and bit 1 - Determine the window size (00=4K, 01=8K, 10=16K, 11=32K)

    4.2. bit 2 - Enable/Disable ANTIC access to the VBXE RAM (what does this mean?)

    4.3. bit 3 - Enable/Disable CPU access to the VBXE RAM (what does this mean?)

    4.4. bit 4,5,6,7 - 4 bytes that points to the bank that holds the window address space. 

    4.5. example of the MEMC byte set: 

           00111000 - $38
                      00 - Window size 4k
                        0 - Disable ANTIC access
                        1 - Enable CPU access,   

                  0011 - Bank 3  address $3000

5. MEMAC-A, To configure the MEMS (bank selection), you should set the following bits.

    5.1. bits 0-6  - selection for 4K (0-7F), 8K (0-3F), 16K (0-1F), 32K (0-F)

    5.2. bit 7 - Enable/Disable the VBXE window

    5.3. example of the MEMS byte set:

           10000000 - $80 
            0000000 - 4K , bank 0 

           1- enable the VBXE window

 

i hope i got most of it correctly. it is still not 100% clear to me, but i did understand most of it.

maybe when you answer my inline questions if will complete my understanding gap.

 

thanks again

 

 

[_The Doctor__]

You must expand the box to see his explanations.

[Yaron Nir]

thank @_The Doctor__

 

@Stephen see my follow-up questions.

 

4 hours ago, Stephen said:

1. The VBXE memory size is 512KB.

    1.1. The VBXE memory address space is between $000000 and $7FFFFF

    1.2. The VBXE memory address is being access via banks. each bank is 4K size ($1000)

Only in this specific example is the window 4kB.  The window can be 4, 8, 16, 32 kB in size but it must always be aligned to $1000.

I am aware that the size of the VBXE window can be 4k/8k/16k/32k , the question is what can be the size of a bank? 

Do banks and the "window" have the same size? 

 

4 hours ago, Stephen said:

2. When planning VBXE memory layout, you should always design the memory addresses space for the following VBXE components:

    2.1. XDL - The extended display list. recommended to be placed in the first bank starting at memory $000000 which is bank0

         2.1.1. As the XDL can be of any size (with the limit of 4K/$1000, It is safe to save size of 256 bytes ($FF) for it and that should be enough

Depending on complexity and changes, an XDL can be anywhere from several bytes to 5.2kB (22 * 240).  Before starting a project, it is imperative you know the display requirements, and what features will be in use.  For MOST simple use cases, a page of RAM will suffice for the XDL.

I'll update my post. thanks.

 

4 hours ago, Stephen said:

2.2. Blitter - (what is the blitter? what is it used for? how is it used ?)

         2.2.1. The blitter size is reserved for blitter command blocks (bcb). each block is 22bytes. (how to use the bcb?) 

         2.2.2. The bcb size can be in bank0 from $000100 to $000FFF

The Blitter is the most advanced feature of the VBXE.  Won't be covered here.  Simply - it's a super fast memory transfer unit.  Think of it as the sprite engine.

why? can we add another section to this thread and explain about the Blitter? sprite engine to me is the most important part of the VBXE and i sure would like to learn more about it. if you think this thread is not a good place, maybe we can open a new thread just for that?

 

5 hours ago, Stephen said:

2.4. Screen ram - the screen memory address space

         2.4.1. for screen resolution 320x240 (should we always reserve the highest screen resolution here?) reserve 13 banks (320x240=76,800)

Only reserve what  you'll be using.  If you're doing a text screen, then the VRAM will only be 4,000 bytes (80X25 * 2 bytes per - character, colour).  Keep in mind - RAM is never "reserved".  Any location can be read / written.  When I say "reserved", I mean I am cognizant of its usage, and will handle read/write access accordingly.

I'll update my post. thanks 

 

5 hours ago, Stephen said:

2.5. Buffers - not sure what are these used for and how?

A buffer is any memory location (or range) that is used for temporary storage.

I'll update my post. thanks 

 

 

thanks again @Stephen

 

 

[+Stephen]

6 hours ago, Yaron Nir said:

 

11 hours ago, Stephen said:

1. The VBXE memory size is 512KB.

    1.1. The VBXE memory address space is between $000000 and $7FFFFF

    1.2. The VBXE memory address is being access via banks. each bank is 4K size ($1000)

Only in this specific example is the window 4kB.  The window can be 4, 8, 16, 32 kB in size but it must always be aligned to $1000.

I am aware that the size of the VBXE window can be 4k/8k/16k/32k , the question is what can be the size of a bank? 

Do banks and the "window" have the same size? 

The bank is simply a number that refers to the "chunk" of RAM being used via the window.  If you are using a 32kB window, you will have 16 available banks (512 / 32).  If you are using a 4kB window, there will be 128 banks available (512 / 4).  Let's use an example of a 4kB window, set to $3000, and bank set to 0.  To access the VBXE, we set the MEMCON registers as above.  Now, when you write to $3000 it goes to VBXE address $000000.  Write to $3500 it goes to VBXE address $000500.  Write to $3FFFF it goes to VBXE $00FFFF.  Well, what happens when you want to write to VBXE RAM $010000?  You cannot just increment and write to $4000.  Because that is outside the 4kB window.  So you must now set the bank to 1 and write to $3000.  Now, that write to $3000 goes to VBXE $001000, $3400 goes to VBXE $005000, $3FFF to VBXE $001FFF.

 

11 hours ago, Stephen said:

2. When planning VBXE memory layout, you should always design the memory addresses space for the following VBXE components:

    2.1. XDL - The extended display list. recommended to be placed in the first bank starting at memory $000000 which is bank0

         2.1.1. As the XDL can be of any size (with the limit of 4K/$1000, It is safe to save size of 256 bytes ($FF) for it and that should be enough

Depending on complexity and changes, an XDL can be anywhere from several bytes to 5.2kB (22 * 240).  Before starting a project, it is imperative you know the display requirements, and what features will be in use.  For MOST simple use cases, a page of RAM will suffice for the XDL.

I'll update my post. thanks.

 

11 hours ago, Stephen said:

2.2. Blitter - (what is the blitter? what is it used for? how is it used ?)

         2.2.1. The blitter size is reserved for blitter command blocks (bcb). each block is 22bytes. (how to use the bcb?) 

         2.2.2. The bcb size can be in bank0 from $000100 to $000FFF

The Blitter is the most advanced feature of the VBXE.  Won't be covered here.  Simply - it's a super fast memory transfer unit.  Think of it as the sprite engine.

why? can we add another section to this thread and explain about the Blitter? sprite engine to me is the most important part of the VBXE and i sure would like to learn more about it. if you think this thread is not a good place, maybe we can open a new thread just for that?

I will certainly do a write up on some of the Blitter features I am using.  But not in this thread - it will be a separate post.  Moving forward I may do these as blog entries since it makes the editing much easier for me.  Keep in mind, I am just beginning and can in no way explain any of the advanced uses of the blitter.

 

[Yaron Nir]

5 minutes ago, Stephen said:

The bank is simply a number that refers to the "chunk" of RAM being used via the window.  If you are using a 32kB window, you will have 16 available banks (512 / 32).  If you are using a 4kB window, there will be 128 banks available (512 / 4).  Let's use an example of a 4kB window, set to $3000, and bank set to 0.  To access the VBXE, we set the MEMCON registers as above.  Now, when you write to $3000 it goes to VBXE address $000000.  Write to $3500 it goes to VBXE address $000500.  Write to $3FFFF it goes to VBXE $00FFFF.  Well, what happens when you want to write to VBXE RAM $010000?  You cannot just increment and write to $4000.  Because that is outside the 4kB window.  So you must now set the bank to 1 and write to $3000.  Now, that write to $3000 goes to VBXE $001000, $3400 goes to VBXE $005000, $3FFF to VBXE $001FFF.

I’ll update my post. Thanks !

 

6 minutes ago, Stephen said:

I will certainly do a write up on some of the Blitter features I am using.  But not in this thread - it will be a separate post.  Moving forward I may do these as blog entries since it makes the editing much easier for me.  Keep in mind, I am just beginning and can in no way explain any of the advanced uses of the blitter.

Whatever we can make out of this is good enough for beginners 

i hope some other developers who has experience with VBXE could chime in and help with the blitter explanation 

@Thelen? Others?

[shanti77]

I suggest starting with the documentation, in case I can suggest something.

fx1.26-en.pdf

[+Stephen]

3 hours ago, Yaron Nir said:

I’ll update my post. Thanks !

 

Whatever we can make out of this is good enough for beginners 

i hope some other developers who has experience with VBXE could chime in and help with the blitter explanation 

@Thelen? Others?

I will put some stuff out, but please give me some time.  It takes an incredibly long time for me to type all this out and try to format / proofread it.  I'm also trying to code as well, and learning while doing that.  I am hoping to have working code of animated masked sprites moving over a background within a few days.  As I said, I can provide both text and graphic examples.  Read the existing 1.26 documentation, and there's plenty of examples with source code in the documentation as well.  Check out the files section here.

[Yaron Nir]

1 hour ago, shanti77 said:

I suggest starting with the documentation, in case I can suggest something.

fx1.26-en.pdf 222.86 kB · 0 downloads

Thank @shanti77,

I am familiar with this document but feel it misses some basic explanations and some examples. that is why i consider contributing to this thread and the other threads on the matter that Stephen will create are most important....

 

[Thelen]

16 hours ago, Yaron Nir said:

i hope some other developers who has experience with VBXE could chime in and help with the blitter explanation 

@Thelen? Others?

Good idea, I will come up with some 'easy' to oversee, and well documted blitter examples!

[Yaron Nir]

2 hours ago, Thelen said:

Good idea, I will come up with some 'easy' to oversee, and well documted blitter examples!

Excellent !

 

[Yaron Nir]

@Stephen, some questions about the XDLC attributes

 

On 1/13/2023 at 1:02 AM, Stephen said:

DLC Byte 1 sets up 5 features.  If a particular feature is set, then the XDL will contain additional data describing it.  This can be an address to load data, or values to apply.

Bit 0 - XDLC_TMON : enable Overlay Text Mode

Bit 1 - XDLC_GMON : enable Overlay Graphics Mode

Bit 2 - XDLC_OVOFF : disable Overlay

              Only 1 bit may be set else the Overlay will be disabled

Bit 3 - XDLC_MAPON : Enable Colour Attributes

Bit 4 - XDLC_MAPOFF :Disable Colour Attributes

              Only 1 bit may be set else the Attributes will be disabled

Bit 5 - XDLC_RPTL : No changes will occur for the next # of scanlines (if repeat = 31, then 32 lines will be displayed)

Bit 6 - XDLC_OVADR : If this bit is set, 5 bytes will be used to determine the VRAM address and step

Bit 7 - XDLC_OVSCRL : If this bit is set, 2 bytes will be used to set fine scroll values for Text mode

 

what are color attributes used for, and how?

I don't understand the OVADR and OVSCRL usage. maybe explain a bit more...?

 

On 1/13/2023 at 1:02 AM, Stephen said:

XDLC Byte 2 sets up 7 features

Bit 0 - XDLC_CHBASE : If set, 1 byte will be used to point to the font (256 characters 8pxX8px , 2kB font) address

Bit 1 - XDLC_MAPADR : If set, 5 bytes will be used to determine the Colour Attribute Map address and step

Bit 2 - XDLC_MAPPAR : If set, 4 bytes will be used to set scrolling values, width, and height of a field in the Colour Attribute Map

Bit 3 - XDLC_ATT : If set, 2 bytes will be used to set display size and Overlay priority with ANTIC

Bit 4 - XDLC_HR : If set, enable the Hi-Res pixel mode (640 pixels represented by 320 bytes)

Bit 5 - XDLC_LR : If set, enable the Lo-Res pixel mode (160 pixels represented by 160 bytes)

Bit 6 - Reserved (unused)

Bit 7 - XDLC_END : If set, marks the last block in the XDL.  Processing is done.  This is analogous to the JMP and wait for VBLANK instruction that all ANTIC Display Lists must end with

- XDLC_CHBASE - so instead of creating a charset with 127 characters (4x8) we are creating a charset with 256 chars (8x8) and double the size (2K instead of 1K). how is it later being used? can you show an example? 

- color attribute map. again, if you can explain more about this.

- not sure about the logic behind 320 bytes to support 640 pixels but 160 bytes to support 160 bytes ? 

 

thanks for all your support! 

 

[Yaron Nir]

6 minutes ago, Yaron Nir said:

I don't understand the OVADR and OVSCRL usage. maybe explain a bit more...?

was trying to figure out myself by reading some more.

is it safe to say that the first attribute is the start address of the screen and the second attribute is the length of 1 scanline?

so in your example you set:

On 1/13/2023 at 1:02 AM, Stephen said:

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

so the 5 bytes address is for the VBXE screen to start and that is set to $013000

and each scanline will be 320 pixels (these are the 2 bytes representing the $140=320) ?

 

is that correct to state? or am i getting this all wrong?

  

[Yaron Nir]

On 1/13/2023 at 1:02 AM, Stephen said:

Bit 3 - XDLC_ATT : If set, 2 bytes will be used to set display size and Overlay priority with ANTIC

i see in your example that this contains some other attributes which are not listed

 

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

maybe we can list those as well with some explanation? 

 

[Rybags]

For bitmap modes there's the 256 and 16 colour modes, so 8 or 4 bits per pixel.

Blitter isn't really relevant in XDL discussion.

 

I'd suggest for a tutorial - take the old IBM approach.  For mainframe OS components there'd be a Reference Manual and a User Guide.

Reference Manual (which VBXE has) is the raw, sometimes hard to understand technical descriptions with the bare essential information to get you going.

User Guide describes things in depth in easier to understand language and has longer practical examples of things.