*
*``````````````````````````````*
* DEMO.LORES                   *
*                              *
* A DEMO OF THE MACROS AND     *
* SUBROUTINES FOR USING LORES  *
* GRAPHICS.                    *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      03-OCT-2019       *
* ASSEMBLER: MERLIN 8 PRO      *
* OS:        DOS 3.3           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** ASSEMBLER DIRECTIVES
*
         CYC   AVE
         EXP   OFF
         TR    ON
         DSK   DEMO.LORES
         OBJ   $BFE0
         ORG   $6000
*
*``````````````````````````````*
*  TOP INCLUDES (PUTS, MACROS) *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
         PUT   MIN.HEAD.REQUIRED.ASM
         PUT   MIN.HEAD.LORES.ASM
         USE   MIN.MAC.REQUIRED.ASM
         USE   MIN.MAC.LORES.ASM
*
*``````````````````````````````*
*      PROGRAM MAIN BODY       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
]COLOR   EQU   VARTAB+16
]HOME    EQU   $FC58
*
*``````````````````````````````*
* LO-RES GRAPHICS COLLECTION   *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THIS DEMO ILLUSTRATES HOW TO USE THE MACROS DEDICATED
** TO CREATING LOW RESOLUTION GRAPHICS. THESE MACROS
** LARGELY CONSIST OF THE MOST BASIC FUNCTIONS NECESSARY
** TO BUILD MORE COMPLICATED ROUTINES, SUCH AS ANIMATION,
** SPRITES, AND SO ON. CURRENTLY, THE MACROS AVAILABLE ARE:
*
** - LVIEWPG : SET THE VIEWING PAGE
** - LWORKPG : SET THE WORKING (PLOTTING) PAGE
** - LRGF    : INIT LOW RESOLUTION FULL SCREEN MODE
** - LRGP    : INIT LOW RESOLUTION PARTIAL SCREEN MODE
** - LFCLR   : CLEAR FULL SCREEN TO SPECIFIED COLOR
** - LPCLR   : CLEAR PARTIAL SCREEN TO SPECIFIED COLOR
** - LPLOT   : PLOT A COLORED PIXEL AT A GIVEN X,Y COORDINATE
** - LLINE   : PLOT LINE FROM X1,Y1 TO X2,Y2
** - LCIRC   : PLOT A CIRCLE WITH A GIVEN CENTER AND RADIUS
** - LVLIN   : PLOT A VERTICAL LINE
** - LHLIN   : PLOT A HORIZONTAL LINE
** - LRGET   : GET COLOR OF A LOW RESOLUTION PIXEL AT X,Y
** - LRCHAR  : PRINT A LOW RESOLUTION CHARACTER AT X,Y
*
*``````````````````````````````*
* WORKING AND VIEWING PAGES    *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** WHILE USING THE LORES COLLECTION, THERE ARE TWO MODES
** TO CONSIDER WHEN PLOTTING: THE WORKING PAGE, WHICH IS
** THE PAGE BEING PLOTTED TO AT A GIVEN MOMENT, AND THE
** VIEWING PAGE, WHICH IS THE PAGE THAT IS CURRENTLY
** VISIBLE ON THE SCREEN. THESE DO NOT HAVE TO BE THE SAME
** PAGE; YOU CAN PLOT TO THE WORKING PAGE WHILE SHOWING THE
** VIEWING PAGE ON SCREEN, AND YOU CAN FLIP THE VIEWING PAGE
** TO THE WORKING PAGE AFTER THE DESIRED PLOTTING IS
** FINISHED. THIS IS MOSTLY HELPFUL FOR ANIMATION, BUT OTHER
** USES ARE BOUND TO BE FOUND. ONE OTHER SUCH USE IS HOLDING
** A STATIC PAGE IN MEMORY TO BE FLIPPED ON OR OFF DEPENDING
** ON THE STATE OF A PROGRAM.
*
** UNFORTUNATELY, MERLIN 8 PRO USES THE SECOND PAGE FOR
** STORING DATA OF ITS OWN, SO ITS USE CANNOT BE SHOWN HERE
** WITHOUT POSSIBLY DESTROYING DATA IN RAM OR PERHAPS EVEN
** ON THE DISK. THUS WE ARE LEFT TO ONLY SHOW THE FORMAT OF
** THE COMMANDS USED.
*
** TO SET THE WORKING PAGE, YOU WOULD USE THE
** LWORKPG MACRO, AS SUCH:
*
** LWORKPG #2
*
** WHICH SETS THE WORKING PAGE TO PAGE 2. TO SET
** THE VIEWING PAGE, YOU WOULD USE THE LVIEWPG MACRO:
*
** LVIEWPG #1
*
** WHICH WOULD SET THE VIEWING PAGE TO PAGE 1. NOTE THAT
** BOTH THE WORKING PAGE AND THE VIEWING PAGE ALWAYS
** DEFAULT TO PAGE 1.
*
*```````````````````````````````*
* LORES GRAPHICS INITIALIZATION *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THERE ARE TWO MACROS FOR INITIALIZING LORES
** GRAPHICS MODE: LRFGR AND LRPGR. THE LRFGR MACRO,
** WHICH STANDS FOR ^LORES FULL GRAPHICS^, INITIALIZES
** THE FULL SCREEN GRAPHICS MODE IN LOW RESOLUTION,
** WHEREAS THE LRPGR MACRO, WHICH STANDS FOR LORES
** PARTIAL GRAPHICS, INITIALIZES THE PARTIAL (OR MIXED)
** GRAPHICS MODE, WHICH RESERVES FOR ROWS OF TEXT SPACE
** AT THE BOTTOM OF THE SCREEN.
*
** NEITHER OF THESE MACROS HAVE ANY PARAMETERS. THE
** LRFGR MACRO CREATES A 40 X 48 LORES SCREEN, AND THE
** LRPGR MACRO CREATES A 40 X 40 MATRIX LORES SCREEN.
*
*``````````````````````````````*
* CLEARING THE LORES SCREEN    *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** LIKE WITH INTIALIZING THE GRAPHICS MODE, THERE ARE
** TWO MACROS DEDICATED TO CLEARING THE SCREEN: LRFCLR
** AND LRPCLR. BOTH OF THESE FUNCTION THE SAME, WITH
** THE EXCEPTION THAT THE LRFCLR MACRO CLEARS THE WHOLE
** SCREEN AND THE LRPCLR MACRO CLEARS ALL BUT THE
** BOTTOM FOUR ROWS (MIXED MODE). IN THIS DEMO, WE WILL
** BE DEALING EXCLUSIVELY WITH FULL SCREEN MODE.
*
** BOTH OF THE SCREEN CLEARING MACROS ACCEPT A PARAMETER
** THAT INDICATES THE COLOR TO FILL THE SCREEN WITH.
*
** NOW WE CAN UTILIZE THE MACROS ABOVE TO SHOW HOW THE
** SCREEN CAN BE CLEARED WITH EVERY COLOR AVAILABLE
** IN LOW RESOLUTION GRAPHICS MODE.
*
         JSR   ]HOME
         LWORKPG #1       ; SET WORKING PAGE AND
         LVIEWPG #1       ; TO PAGE 1. PAGE 2 WILL NOT WORK
         LRGF             ; WITH MERLIN LOADED; THEN, INIT
         LDY   #$FF       ; LORES GRAPHICS FULL SCREEN MODE
         STY   ]COLOR     ; MAC COLOR - 1
:LP1
         INC   ]COLOR     ; INCREASE THE COLOR
         LFCLR ]COLOR     ; CLEAR FULL SCREEN WITH COLOR SELECTED
         _WAIT            ; WAIT UNTIL KEYPRESS
         LDA   ]COLOR     ; LOAD COLOR AGAIN
         CMP   #$F        ; IF IT'S $F (15), THEN
         BNE   :LP1       ; WE ARE DONE DEMOING SCREEN FILLS
*
*``````````````````````````````*
* RE-ENTERING TEXT MODE        *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** A SOFT SWITCH IS USED TO RE-ENTER TEXT MODE. ANY
** INSTRUCTION CAN BE USED ON THE ^TEXTON^ MEMORY
** ADDRESS IN ORDER TO DO THIS; I USUALLY USE THE BIT
** INSTRUCTION SINCE I RARELY USE IT FOR OTHER
** PURPOSES.
*
         BIT   TEXTON
         JSR   ]HOME
         _PRN  "LOOK MA, TEXT MODE!",8D8D
         _WAIT
*
*``````````````````````````````*
* PLOTTING MACROS              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THERE ARE A NUMBER OF MACROS DEDICATED TO PLOTTING
** POINTS ONTO THE LOW RESOLUTION SCREEN. THESE ARE
** LPLOT, LHLIN, LVLIN, LLINE AND LCIRC. THESE WILL ALL
** BE SHOWN ON THE SAME GRAPHICS SCREEN, BUT EACH
** DESERVES A SHORT EXPLANATION.
*
*``````````````````````````````*
* THE LPLOT MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE LPLOT MACRO ACCEPTS AN X-COORDINATE AND A
** Y-COORDINATE, AS WELL AS A COLOR FOR THE LORES
** PIXEL TO BE PLOTTED.
*
*``````````````````````````````*
* THE LHLIN MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE LHLIN MACRO ACCEPTS A STARTING X POINT AND AN
** ENDING X-COORDINATE, FOLLOWED BY A Y-COORDINATE THAT
** THE LINE WILL APPEAR ON. OBVIOUSLY, THIS CREATES A
** HORIZONTAL LINE ON THE SCREEN. THE LAST PARAMETER
** SIGNIFIES THE COLOR OF THE LINE.
*
*``````````````````````````````*
* THE LVLIN MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE LVLIN MACRO WORKS MUCH THE SAME AS THE LHLIN
** MACRO, EXCEPT IT PRINTS A VERTICAL LINE. THE FIRST
** PARAMETER IS A STARTING Y-COORDINATE, FOLLOWED BY
** AN ENDING Y-COORDINATE. THE THIRD PARAMETER IS THE
** X-COORDINATE OF THE LINE, AND THE FOURTH PARAMETER
** IS THE COLOR TO BE USED FOR THE LINE.
*
*``````````````````````````````*
* THE LLINE MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE LLINE MACRO USES BRESSENHAM'S LINE ALGORITHM
** TO PLOT A LINE WITH AN ARBITRARY ANGLE TO THE
** LOW RESOLUTION SCREEN. ITS FORMAT IS AS FOLLOWS:
*
** LLINE X1;Y1;X2;Y2;COLOR
*
** NOTE THAT IF YOU KNOW BEFOREHAND THAT THE LINE WILL
** BE PERFECTLY VERTICAL OR HORIZONTAL, LHLIN OR LVLIN
** SHOULD ALWAYS BE USED INSTEAD IN ORDER TO SAVE
** CYCLES.
*
*``````````````````````````````*
* LCIRC                        *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** FINALLY, THE LCIRC MACRO PLOTS A CIRCLE TO THE LOW
** RESOLUTION SCREEN AT A GIVEN CENTER COORDINATE WITH
** A GIVEN RADIUS AND COLOR, AS SUCH:
*
** LCIRC X;Y;CENTER;COLOR
*
** THIS MACRO/SUBROUTINE USES BRESSENHAM'S CIRCLE
** ALGORITHM, WHICH SACRIFICES SOME ACCURACY IN THE
** NAME OF SPEED. EVEN IN HIGH RESOLUTION GRAPHICS ON
** THE APPLE II, THE POTENTIAL FOR ERROR IS NEGLIGIBLE
** DUE TO THE LIMITED RESOLUTION THAT THE MACHINE IS
** CAPABLE OF DISPLAYING.
*
         JSR   ]HOME
         LRGF
         LFCLR #]WHITE
         LPLOT #10;#10;#]MAGENTA ; PLOT MAGENTA PIXEL AT 10,10
         LPLOT #11;#11;#]PINK    ; PLOT PINK PIXEL AT 11,11
         _WAIT
*
         LHLIN #15;#30;#2;#]PURPLE ; NOW DRAW A HORIZONTAL
         _WAIT
*
         LVLIN #2;#17;#30;#]YELLOW ; NOW CREATE A YELLOW VERTICAL LINE
         _WAIT
         LLINE #1;#1;#05;#47;#]ORANGE ; NOW PLOT ORGANGE DIAGONAL
         _WAIT
         LLINE #1;#1;#10;#47;#]ORANGE
         _WAIT
         LLINE #1;#1;#15;#47;#]ORANGE
         _WAIT
         LLINE #1;#1;#20;#47;#]ORANGE
         _WAIT
         LLINE #1;#1;#25;#47;#]ORANGE
         _WAIT
         LLINE #1;#1;#30;#47;#]ORANGE
         _WAIT
         LLINE #1;#1;#35;#47;#]ORANGE
         _WAIT
         LLINE #1;#1;#39;#47;#]ORANGE
         _WAIT
*
         LCIRC #10;#10;#10;#]LBLUE ; NOW DRAW A LIGHT BLUE CIRCLE
         _WAIT
*
*``````````````````````````````*
* THE LRGET MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE LRGET MACRO RETRIEVES THE COLOR VALUE OF A
** LOW RESOLUTION PIXEL AT THE GIVEN COORDINATES, AS
** SUCH:
*
** LRGET X;Y
*
         LRGET #38;#38    ; NOW GET THE COLOR OF A GIVE PIXEL
         BIT   TEXTON
         JSR   ]HOME
         DUMP  #RETURN;#1
         _WAIT
*
*``````````````````````````````*
* THE LCHAR MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE LCHAR MACRO PRINTS A 4 X 6 CHARACTER TO THE
** LOW RESOLUTION SCREEN AT THE SPECIFIED COLOR. THIS
** MEANS THAT A THE SCREEN CAN HOLD A TOTAL OF 8 X 8
** CHARACTERS ON THE SCREEN AT ONCE, WITH A SINGLE
** BLANK PIXEL BETWEEN EACH CHARACTER.
*
         LRGF             ; GO BACK TO FULL SCREEN LORES GRAPHICS
         LFCLR #]WHITE    ; CLEAR THE BACKGROUND TO WHITE
         LCHAR #0;#0;#LR_A;#0
         LCHAR #5;#0;#LR_B;#1
         LCHAR #10;#0;#LR_C;#2
         LCHAR #15;#0;#LR_D;#3
         LCHAR #20;#0;#LR_E;#4
         LCHAR #25;#0;#LR_F;#5
         LCHAR #30;#0;#LR_G;#6
         LCHAR #35;#0;#LR_H;#7
         LCHAR #0;#6;#LR_I;#8
         LCHAR #5;#6;#LR_J;#9
         LCHAR #10;#6;#LR_K;#10
         LCHAR #15;#6;#LR_L;#11
         LCHAR #20;#6;#LR_M;#12
         LCHAR #25;#6;#LR_N;#13
         LCHAR #30;#6;#LR_O;#14
         LCHAR #35;#6;#LR_P;#0
         LCHAR #0;#12;#LR_Q;#1
         LCHAR #5;#12;#LR_R;#2
         LCHAR #10;#12;#LR_S;#3
         LCHAR #15;#12;#LR_T;#4
         LCHAR #20;#12;#LR_U;#5
         LCHAR #25;#12;#LR_V;#6
         LCHAR #30;#12;#LR_W;#7
         LCHAR #35;#12;#LR_X;#8
         LCHAR #0;#18;#LR_Y;#9
         LCHAR #5;#18;#LR_Z;#10
         LCHAR #10;#18;#LR_0;#11
         LCHAR #15;#18;#LR_1;#12
         LCHAR #20;#18;#LR_2;#13
         LCHAR #25;#18;#LR_3;#14
         LCHAR #30;#18;#LR_4;#0
         LCHAR #35;#18;#LR_5;#1
         LCHAR #0;#24;#LR_6;#2
         LCHAR #5;#24;#LR_7;#3
         LCHAR #10;#24;#LR_8;#4
         LCHAR #15;#24;#LR_9;#5
         LCHAR #20;#24;#LR_EXC;#6
         LCHAR #25;#24;#LR_QUEST;#7
         LCHAR #30;#24;#LR_PRD;#8
         LCHAR #35;#24;#LR_CMA;#9
         LCHAR #0;#30;#LR_APOST;#10
         LCHAR #5;#30;#LR_QUOT;#11
         LCHAR #10;#30;#LR_COLON;#12
         LCHAR #15;#30;#LR_SEMI;#13
         LCHAR #20;#30;#LR_MINUS;#14
         LCHAR #25;#30;#LR_PLUS;#0
         LCHAR #30;#30;#LR_EQUAL;#1
         LCHAR #35;#30;#LR_FSLASH;#8
         LCHAR #05;#36;#LR_BSLASH;#9
         LCHAR #10;#36;#LR_LPAR;#10
         LCHAR #15;#36;#LR_RPAR;#11
         _WAIT
*
*``````````````````````````````*
* YEET                         *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FOLLOWING SHOWS A QUICK EXAMPLE OF MANY
** OF THESE MACROS ACTING TOGETHER. THIS IS NOTHING
** TERRIBLY IMPRESSIVE, BUT IT DOES DEMONSTRATE SOME
** OF WHAT THE LIBRARY DOES.
*
         LRGF
         LFCLR #]BLACK
         LDA   #1
         STA   ]CC1
:RELOOP
         LVLIN #0;#47;]HH;]CC1
         INC   ]HH
         INC   ]CC1
         LDY   ]HH
         CPY   #40
         BNE   :CONTLP0
         LDA   #0
         STA   ]HH
*
:CONTLP0
         LCHAR #10;#37;#LR_K;#0
         LCHAR #15;#38;#LR_I;#0
         LCHAR #20;#39;#LR_L;#0
         LCHAR #25;#40;#LR_L;#0
         INC   ]CC1
         LDY   ]CC1
         CPY   #15
         BNE   :CONTLP
         LDY   #1
         STY   ]CC1
:CONTLP
         LDA   #1
         STA   ]CC
         STA   ]RR
:LPC
         LCIRC #19;#19;]RR;]CC
         INC   ]RR
         INC   ]CC
         LDY   ]RR
         CPY   #15
         BEQ   :QLPC
         JMP   :LPC
:QLPC
         LDA   #1
         STA   ]CC
:LPC2
         LCIRC #19;#19;]RR;]CC
         DEC   ]RR
         INC   ]CC
         LDY   ]RR
         CPY   #1
         BNE   :LPC2
         LDA   $C000      ; CHECK FOR KEYPRESS
         BPL   :LPLP      ; IF NONE, KEEP LOOPING
         AND   #$7F       ; SET HIGH BIT
         STA   $C010      ; RESET KEYBOARD STROBE
         JMP   EXIT
*JMP :RELOOP
*
:LPLP
         JMP   :RELOOP
EXIT
         BIT   TEXTON
         JSR   ]HOME
         _PRN  "FIN!",8D8D
         LDA   TEXTON
         JMP   $3D0
*
*``````````````````````````````*
*        BOTTOM INCLUDES       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** BOTTOM INCLUDES
*
         PUT   MIN.LIB.REQUIRED.ASM
*
** INDIVIDUAL SUBROUTINE INCLUDES
*
         PUT   MIN.SUB.LRGFCLR.ASM
         PUT   MIN.SUB.LRGPCLR.ASM
         PUT   MIN.SUB.LRPLOT.ASM
         PUT   MIN.SUB.LRHLINE.ASM
         PUT   MIN.SUB.LRVLINE.ASM
         PUT   MIN.SUB.LRBLINE.ASM
         PUT   MIN.SUB.LRCIRCLE.ASM
         PUT   MIN.SUB.LRGETPIX.ASM
         PUT   MIN.SUB.LRCHAR.ASM
*
]RR      DS    1
]CC      DS    1
]HH      DS    1
]CC1     DS    1
