VDP commands (High level APIs)

Execute, Stop, and Await VDP commands. More...

Collaboration diagram for VDP commands (High level APIs):

Enumerations
enum	vdp_cmd_logop {   VDP_CMD_IMP = 0x00 , VDP_CMD_AND = 0x01 , VDP_CMD_OR = 0x02 , VDP_CMD_EOR = 0x03 ,   VDP_CMD_XOR = VDP_CMD_EOR , VDP_CMD_NOT = 0x04 , VDP_CMD_TIMP = 0x08 , VDP_CMD_TAND = 0x09 ,   VDP_CMD_TOR = 0x0a , VDP_CMD_TEOR = 0x0b , VDP_CMD_TXOR = VDP_CMD_TEOR , VDP_CMD_TNOT = 0x0c }
	Enumeration of logical operation codes for VDP commands. More...
enum	vdp_cmd_dir { VDP_CMD_LRTB = (0 << 2) , VDP_CMD_RLTB = (1 << 2) , VDP_CMD_LRBT = (2 << 2) , VDP_CMD_RLBT = (3 << 2) }
	Enumeration of directions of rectangular operation for VDP commands. More...

Functions
bool	vdp_cmd_is_running (void)
	MSX2 Tests if a VDP command is running.
void	vdp_cmd_await (void)
	MSX2 Wait for the VDP command to finish.
void	vdp_cmd_set_unrestricted (bool enable)
	MSX2+ Unristricts/Restricts availability of the VDP command for some screen modes.
void	vdp_cmd_stop (void)
	MSX2 Executes VDP command "STOP" (stop the running VDP command).
uint8_t	vdp_cmd_execute_POINT (uint16_t sx, uint16_t sy)
	MSX2 Executes VDP command "POINT" (Read color code at the given point).
void	vdp_cmd_execute_PSET (uint16_t dx, uint16_t dy, uint8_t color, enum vdp_cmd_logop logop)
	MSX2 Executes VDP command "PSET" (Write color code at the given point).
bool	vdp_cmd_execute_SRCH (uint16_t *ret, uint16_t sx, uint16_t sy, uint8_t color, uint8_t arg)
	MSX2 Executes VDP command "SRCH" (Search color code from the given point towards left/right).
void	vdp_cmd_execute_LINE (uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2, uint8_t color, enum vdp_cmd_logop logop)
	MSX2 Executes VDP command "LINE" (Draw line w/ logical operation).
bool	vdp_cmd_read (uint8_t *ret)
	MSX2 Reads a value from VDP.
void	vdp_cmd_execute_LMCM (uint16_t x, uint16_t y, uint16_t w, uint16_t h, enum vdp_cmd_dir dir)
	MSX2 Executes VDP command "LMCM" (VRAM to CPU logical transfer).
bool	vdp_cmd_write (const uint8_t val)
	MSX2 Writes a value to VDP.
void	vdp_cmd_execute_LMMC (uint16_t x, uint16_t y, uint16_t w, uint16_t h, enum vdp_cmd_dir dir, enum vdp_cmd_logop logop)
	MSX2 Executes VDP command "LMMC" (CPU to VRAM logical transfer).
void	vdp_cmd_execute_HMMC (uint16_t x, uint16_t y, uint16_t w, uint16_t h, enum vdp_cmd_dir dir)
	MSX2 Executes VDP command "HMMC" (CPU to VRAM high speed transfer).
void	vdp_cmd_execute_LMMV (uint16_t x, uint16_t y, uint16_t w, uint16_t h, uint8_t color, enum vdp_cmd_logop logop)
	MSX2 Executes VDP command "LMMV" (fills rectangular area w/ logical operation).
void	vdp_cmd_execute_LMMM (uint16_t x, uint16_t y, uint16_t w, uint16_t h, uint16_t x2, uint16_t y2, enum vdp_cmd_logop logop)
	MSX2 Executes VDP command "LMMM" (copy rectangular area w/ logical operation).
void	vdp_cmd_execute_HMMV (uint16_t x, uint16_t y, uint16_t w, uint16_t h, uint8_t color)
	MSX2 Executes VDP command "HMMV" (fills rectangular area).
void	vdp_cmd_execute_HMMM (uint16_t x, uint16_t y, uint16_t w, uint16_t h, uint16_t x2, uint16_t y2)
	MSX2 Executes VDP command "HMMM" (copy rectangular area).
void	vdp_cmd_execute_YMMM (uint16_t x, uint16_t y, uint16_t h, uint16_t y2, uint8_t dir)
	MSX2 Executes VDP command "YMMM" (copy rectangular area from VRAM to VRAM vertically).

Detailed Description

Execute, Stop, and Await VDP commands.

Enumeration Type Documentation

vdp_cmd_logop

enum vdp_cmd_logop

Enumeration of logical operation codes for VDP commands.

See also

vdp_cmd_execute()

Enumerator
VDP_CMD_IMP	Logical operation code "IMP" : destination ← source.
VDP_CMD_AND	Logical operation code "AND" : destination ← destination & source.
VDP_CMD_OR	Logical operation code "OR" : destination ← destination | source.
VDP_CMD_EOR	Logical operation code "EOR" : destination ← destination ^ source.
VDP_CMD_XOR	(synonim for VDP_CMD_EOR)
VDP_CMD_NOT	Logical operation code "NOT" : destination ← ~source.
VDP_CMD_TIMP	Logical operation code "TIMP" : destination ← source , if source ≠ 0.
VDP_CMD_TAND	Logical operation code "TAND" : destination ← destination & source , if source ≠ 0.
VDP_CMD_TOR	Logical operation code "TOR" : destination ← destination | source , if source ≠ 0.
VDP_CMD_TEOR	Logical operation code "TEOR" : destination ← destination ^ source , if source ≠ 0.
VDP_CMD_TXOR	(synonim for VDP_CMD_TEOR)
VDP_CMD_TNOT	Logical operation code "TNOT" : destination ← ~source , if source ≠ 0.

Definition at line 628 of file vdp.h.

vdp_cmd_dir

enum vdp_cmd_dir

Enumeration of directions of rectangular operation for VDP commands.

See also

vdp_cmd_execute_LMCM()

vdp_cmd_execute_LMMC()

vdp_cmd_execute_HMMC()

Enumerator
VDP_CMD_LRTB	Left to Right, Top to Bottom.
VDP_CMD_RLTB	Right to Left, Top to Bottom.
VDP_CMD_LRBT	Left to Right, Bottom to Top.
VDP_CMD_RLBT	Right to Left, Bottom to Top.

Definition at line 661 of file vdp.h.

Function Documentation

vdp_cmd_is_running()

bool vdp_cmd_is_running ( void  )

inline

MSX2 Tests if a VDP command is running.

Returns

true is a VDP command is running, false otherwise.

See also

vdp_cmd_execute()

Definition at line 598 of file vdp.h.

vdp_cmd_await()

void vdp_cmd_await ( void  )

inline

MSX2 Wait for the VDP command to finish.

See also

vdp_cmd_execute()

Definition at line 607 of file vdp.h.

vdp_cmd_set_unrestricted()

void vdp_cmd_set_unrestricted

(

bool

enable

)

MSX2+ Unristricts/Restricts availability of the VDP command for some screen modes.

Parameters

enable

If true, enables the VDP command for all screen modes. Otherwise, enables the VDP command only for GRAPHIC 4 to 7.

See also

vdp_cmd_execute()

vdp_set_screen_mode()

vdp_cmd_stop()

void vdp_cmd_stop ( void  )

inline

MSX2 Executes VDP command "STOP" (stop the running VDP command).

Definition at line 671 of file vdp.h.

vdp_cmd_execute_POINT()

uint8_t vdp_cmd_execute_POINT	(	uint16_t	sx,
		uint16_t	sy
	)

MSX2 Executes VDP command "POINT" (Read color code at the given point).

Parameters

sx	x-coordinate (0..511)
sy	y-coordinate (0..1023)

Returns

color code at (sx, sy)

vdp_cmd_execute_PSET()

void vdp_cmd_execute_PSET	(	uint16_t	dx,
		uint16_t	dy,
		uint8_t	color,
		enum vdp_cmd_logop	logop
	)

MSX2 Executes VDP command "PSET" (Write color code at the given point).

Parameters

dx	x-coordinate (0..511)
dy	y-coordinate (0..1023)
color	color code
logop	logical operation code

vdp_cmd_execute_SRCH()

bool vdp_cmd_execute_SRCH	(	uint16_t *	ret,
		uint16_t	sx,
		uint16_t	sy,
		uint8_t	color,
		uint8_t	arg
	)

MSX2 Executes VDP command "SRCH" (Search color code from the given point towards left/right).

Parameters

ret	pointer to a variable where the X coordinate of the detected point is stored.
sx	x-coordinate (0..511)
sy	y-coordinate (0..1023)
color	color code
arg	argument register value bit #2 : (0) search towards right, (1) search towards left. bit #1 : (0) search the specified color, (1) search except for the specified color.

Returns

true if found, false otherwise.

vdp_cmd_execute_LINE()

void vdp_cmd_execute_LINE	(	uint16_t	x1,
		uint16_t	y1,
		uint16_t	x2,
		uint16_t	y2,
		uint8_t	color,
		enum vdp_cmd_logop	logop
	)

MSX2 Executes VDP command "LINE" (Draw line w/ logical operation).

Parameters

x1	x-coordinate of the 1st end point (0..511)
y1	y-coordinate of the 1st end point (0..1023)
x2	x-coordinate of the 2nd end point (0..511)
y2	y-coordinate of the 2nd end point (0..1023)
color	color code
logop	logical operation code

vdp_cmd_read()

bool vdp_cmd_read

(

uint8_t *

ret

)

MSX2 Reads a value from VDP.

Parameters

ret	pointer to a variable where the value read from VDP is stored.

Returns

true if succeeded, otherwise false.

See also

vdp_cmd_execute_LMCM()

vdp_cmd_execute_LMCM()

void vdp_cmd_execute_LMCM	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		enum vdp_cmd_dir	dir
	)

MSX2 Executes VDP command "LMCM" (VRAM to CPU logical transfer).

Set VDP to read out pixel values in the rectangular area of VRAM.

The pixel values (i.e. color code) can then be read by calling vdp_cmd_read().

After this function, vdp_cmd_read() should be called repeatedly, or vdp_cmd_stop() should be called if the read operation is to be canceled.

 c
// Read out **pixel** values in the rectangular area (0,0)..(7,7) into `pixels[]`.
 
#define WIDTH        (8) // Width 8-pixels
#define HEIGHT       (8) // Height 8-pixels
 
uint8_t pixels[8*8];
 
vdp_cmd_execute_LMCM(0, 0, WIDTH, HEIGHT, VDP_CMD_LRTB);
uint8_t * p = &pixels[0];
for (uint8_t n = sizeof(pixels); n--; ) {
  if (!vdp_cmd_read(p++)) {
    // failed to read (the command maight be terminated)
    break;
  }
}

Parameters

x	x-coordinate of the starting point (0..511)
y	y-coordinate of the starting point (0..1023)
w	width (1..512)
h	height (1..1024)
dir	direction VDP_CMD_LRTB : Left to right, top to bottom VDP_CMD_RLTB : Right to left, top to bottom VDP_CMD_LRBT : Left to right, bottom to top VDP_CMD_RLBT : Right to left, bottom to top

See also

vdp_cmd_read()

vdp_cmd_stop()

vdp_cmd_write()

bool vdp_cmd_write

(

const uint8_t

val

)

MSX2 Writes a value to VDP.

Parameters

val	the value to be written to VDP.

Returns

true if succeeded, otherwise false.

See also

vdp_cmd_execute_LMMC()

vdp_cmd_execute_HMMC()

vdp_cmd_execute_LMMC()

void vdp_cmd_execute_LMMC	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		enum vdp_cmd_dir	dir,
		enum vdp_cmd_logop	logop
	)

MSX2 Executes VDP command "LMMC" (CPU to VRAM logical transfer).

Set VDP to write out pixel values in the rectangular area of VRAM.

The pixel values (i.e. color code) can then be written by calling vdp_cmd_write().

After this function, vdp_cmd_write() should be called repeatedly, or vdp_cmd_stop() should be called if the write operation is to be canceled.

 c
// Write out **pixel** values in `pixels[]` into the rectangular area (0,0)..(7,7).
 
#define WIDTH        (8) // Width 8-pixels
#define HEIGHT       (8) // Height 8-pixels
 
uint8_t pixels[WIDTH * HEIGHT] = { ... };
 
vdp_cmd_execute_LMMC(0, 0, WIDTH, HEIGHT, VDP_CMD_LRTB, VDP_CMD_IMP);
uint8_t * p = &pixels[0];
for (uint8_t n = sizeof(pixels); n--; ) {
  if (!vdp_cmd_write(*p++)) {
    // failed to write (the command maight be terminated)
    break;
  }
}

Parameters

x	x-coordinate of the starting point (0..511)
y	y-coordinate of the starting point (0..1023)
w	width (1..512)
h	height (1..1024)
dir	direction VDP_CMD_LRTB : Left to right, top to bottom VDP_CMD_RLTB : Right to left, top to bottom VDP_CMD_LRBT : Left to right, bottom to top VDP_CMD_RLBT : Right to left, bottom to top
logop	logical operation code

See also

vdp_cmd_write()

vdp_cmd_stop()

vdp_cmd_execute_HMMC()

void vdp_cmd_execute_HMMC	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		enum vdp_cmd_dir	dir
	)

MSX2 Executes VDP command "HMMC" (CPU to VRAM high speed transfer).

Set VDP to write out byte values in the rectangular area of VRAM.

The byte values can then be written by calling vdp_cmd_write().

After this function, vdp_cmd_write() should be called repeatedly, or vdp_cmd_stop() should be called if the write operation is to be canceled.

 c
// Write out **byte** values in `bytes[]` into the rectangular area (0,0)..(7,7).
 
#define WIDTH        (8) // Width 8-pixels
#define HEIGHT       (8) // Height 8-pixels
#define BPP          (4) // Number of bits per pixel
                         // - `4` for SCREEN 5 and 7,
                         // - `2` for SCREEN 6,
                         // - `8` for SCREEN 8.
#define PIX_PER_BYTE (8 / BPP)
#define NUM_BYTES  ((WIDTH + PIX_PER_BYTE - 1) / PIX_PER_BYTE * HEIGHT)
 
uint8_t bytes[NUM_BYTES] = { ... };
 
vdp_cmd_execute_HMMC(0, 0, WIDTH, HEIGHT, VDP_CMD_LRTB);
uint8_t * p = &bytes[0];
for (size_t n = sizeof(bytes); n--; ) {
  if (!vdp_cmd_write(*p++)) {
    // failed to write (the command maight be terminated)
    break;
  }
}

Parameters

x	x-coordinate of the starting point (0..511)
y	y-coordinate of the starting point (0..1023)
w	width (1..512)
h	height (1..1024)
dir	direction VDP_CMD_LRTB : Left to right, top to bottom VDP_CMD_RLTB : Right to left, top to bottom VDP_CMD_LRBT : Left to right, bottom to top VDP_CMD_RLBT : Right to left, bottom to top

See also

vdp_cmd_write()

vdp_cmd_stop()

Note

The parameter x and w must be aligned to byte address of VRAM.
In other words,

• LSB 1-bits are omitted for 4-bpp mode; 2 pixels per byte; GRAPHIC 4 and 6 (SCREEN 5 and 7),
• LSB 2-bits are omitted for 2-bpp mode; 4 pixels per byte; GRAPHIC 5 (SCREEN 6).
• No bits are omitted for 8-bpp mode ; 1 pixels per byte; GRAPHIC 7 (SCREEN 8).

vdp_cmd_execute_LMMV()

void vdp_cmd_execute_LMMV	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		uint8_t	color,
		enum vdp_cmd_logop	logop
	)

MSX2 Executes VDP command "LMMV" (fills rectangular area w/ logical operation).

This function is equivalent to the following code:

struct vdp_cmd c;
vdp_cmd_set_DX(&c, x);
vdp_cmd_set_DY(&c, y);
vdp_cmd_set_NX(&c, w);
vdp_cmd_set_NY(&c, h);
vdp_cmd_set_CLR(&c, color);
vdp_cmd_set_ARG(&c, 0);
vdp_cmd_set_logop(&c, logop);
vdp_cmd_execute(&c, VDP_CMD_LMMV);

Parameters

x	x-coordinate of the top-left corner of the rectangular area.
y	y-coordinate of the top-left corner of the rectangular area.
w	width of the rectangular area.
h	height of the rectangular area.
color	color code.
logop	logical operation code.

See also

vdp_cmd_execute()

vdp_cmd_execute_LMMM()

void vdp_cmd_execute_LMMM	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		uint16_t	x2,
		uint16_t	y2,
		enum vdp_cmd_logop	logop
	)

MSX2 Executes VDP command "LMMM" (copy rectangular area w/ logical operation).

This function is equivalent to the following code, as long as the intersection of the source and destination areas is not considered.

struct vdp_cmd c;
vdp_cmd_set_SX(&c, x);
vdp_cmd_set_SY(&c, y);
vdp_cmd_set_DX(&c, x2);
vdp_cmd_set_DY(&c, y2);
vdp_cmd_set_NX(&c, w);
vdp_cmd_set_NY(&c, h);
vdp_cmd_set_ARG(&c, 0);
vdp_cmd_set_logop(&c, logop);
vdp_cmd_execute(&c, VDP_CMD_LMMM);

Parameters

x	x-coordinate of the top-left corner of the source rectangular area.
y	y-coordinate of the top-left corner of the source rectangular area.
x2	x-coordinate of the top-left corner of the destination rectangular area.
y2	y-coordinate of the top-left corner of the destination rectangular area.
w	width of the rectangular area.
h	height of the rectangular area.
logop	logical operation code.

See also

vdp_cmd_execute()

vdp_cmd_execute_HMMV()

void vdp_cmd_execute_HMMV	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		uint8_t	color
	)

MSX2 Executes VDP command "HMMV" (fills rectangular area).

This function is equivalent to the following code:

struct vdp_cmd c;
vdp_cmd_set_DX(&c, x);
vdp_cmd_set_DY(&c, y);
vdp_cmd_set_NX(&c, w);
vdp_cmd_set_NY(&c, h);
vdp_cmd_set_CLR(&c, color);
vdp_cmd_set_ARG(&c, 0);
vdp_cmd_set_logop(&c, 0);
vdp_cmd_execute(&c, VDP_CMD_HMMV);

Parameters

x	x-coordinate of the top-left corner of the rectangular area.
y	y-coordinate of the top-left corner of the rectangular area.
w	width of the rectangular area.
h	height of the rectangular area.
color	color code.

See also

vdp_cmd_execute()

Note

The parameter x and w must be aligned to byte address of VRAM.
In other words,

• LSB 1-bits are omitted for 4-bpp mode; 2 pixels per byte; GRAPHIC 4 and 6 (SCREEN 5 and 7),
• LSB 2-bits are omitted for 2-bpp mode; 4 pixels per byte; GRAPHIC 5 (SCREEN 6).
• No bits are omitted for 8-bpp mode ; 1 pixels per byte; GRAPHIC 7 (SCREEN 8).

vdp_cmd_execute_HMMM()

void vdp_cmd_execute_HMMM	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		uint16_t	x2,
		uint16_t	y2
	)

MSX2 Executes VDP command "HMMM" (copy rectangular area).

This function is equivalent to the following code, as long as the intersection of the source and destination areas is not considered.

struct vdp_cmd c;
vdp_cmd_set_SX(&c, x);
vdp_cmd_set_SY(&c, y);
vdp_cmd_set_DX(&c, x2);
vdp_cmd_set_DY(&c, y2);
vdp_cmd_set_NX(&c, w);
vdp_cmd_set_NY(&c, h);
vdp_cmd_set_ARG(&c, 0);
vdp_cmd_set_logop(&c, 0);
vdp_cmd_execute(&c, VDP_CMD_HMMM);

Parameters

x	x-coordinate of the top-left corner of the source rectangular area.
y	y-coordinate of the top-left corner of the source rectangular area.
x2	x-coordinate of the top-left corner of the destination rectangular area.
y2	y-coordinate of the top-left corner of the destination rectangular area.
w	width of the rectangular area.
h	height of the rectangular area.

See also

vdp_cmd_execute()

Note

The parameter x, x2, and w must be aligned to byte address of VRAM.
In other words,

• LSB 1-bits are omitted for 4-bpp mode; 2 pixels per byte; GRAPHIC 4 and 6 (SCREEN 5 and 7),
• LSB 2-bits are omitted for 2-bpp mode; 4 pixels per byte; GRAPHIC 5 (SCREEN 6).
• No bits are omitted for 8-bpp mode ; 1 pixels per byte; GRAPHIC 7 (SCREEN 8).

vdp_cmd_execute_YMMM()

void vdp_cmd_execute_YMMM	(	uint16_t	x,
		uint16_t	y,
		uint16_t	h,
		uint16_t	y2,
		uint8_t	dir
	)

MSX2 Executes VDP command "YMMM" (copy rectangular area from VRAM to VRAM vertically).

This function is equivalent to the following code, as long as the intersection of the source and destination areas is not considered.

struct vdp_cmd c;
vdp_cmd_set_SY(&c, y);
vdp_cmd_set_DX(&c, x);
vdp_cmd_set_DY(&c, y2);
vdp_cmd_set_NY(&c, h);
vdp_cmd_set_ARG(&c, dir);
vdp_cmd_set_logop(&c, 0);
vdp_cmd_execute(&c, VDP_CMD_YMMM);

Parameters

x	x-coordinate of the base point of the source / destination rectangular area.
y	y-coordinate of the base point of the source rectangular area.
y2	y-coordinate of the base point of the destination rectangular area.
h	height of the rectangular area.
dir	(0) move right side area, (4) move left side area.

See also

vdp_cmd_execute()

Note

The parameter x must be aligned to byte address of VRAM.
In other words,

• LSB 1-bits are omitted for 4-bpp mode; 2 pixels per byte; GRAPHIC 4 and 6 (SCREEN 5 and 7),
• LSB 2-bits are omitted for 2-bpp mode; 4 pixels per byte; GRAPHIC 5 (SCREEN 6).
• No bits are omitted for 8-bpp mode ; 1 pixels per byte; GRAPHIC 7 (SCREEN 8).