FabGL
ESP32 VGA Controller and Graphics Library
terminal.h
Go to the documentation of this file.
1 /*
2  Created by Fabrizio Di Vittorio (fdivitto2013@gmail.com) - <http://www.fabgl.com>
3  Copyright (c) 2019 Fabrizio Di Vittorio.
4  All rights reserved.
5 
6  This file is part of FabGL Library.
7 
8  FabGL is free software: you can redistribute it and/or modify
9  it under the terms of the GNU General Public License as published by
10  the Free Software Foundation, either version 3 of the License, or
11  (at your option) any later version.
12 
13  FabGL is distributed in the hope that it will be useful,
14  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  GNU General Public License for more details.
17 
18  You should have received a copy of the GNU General Public License
19  along with FabGL. If not, see <http://www.gnu.org/licenses/>.
20  */
21 
22 
23 #ifndef _TERMINAL_H_INCLUDED
24 #define _TERMINAL_H_INCLUDED
25 
26 
35 #include "Arduino.h"
36 
37 #include "freertos/FreeRTOS.h"
38 #include "freertos/task.h"
39 #include "freertos/timers.h"
40 #include "freertos/semphr.h"
41 
42 #include "fabglconf.h"
43 #include "canvas.h"
44 #include "keyboard.h"
45 
46 #include "Stream.h"
47 
48 
49 
215 namespace fabgl {
216 
217 
218 
219 
220 // used by saveCursorState / restoreCursorState
221 struct TerminalCursorState {
222  TerminalCursorState * next;
223  int16_t cursorX;
224  int16_t cursorY;
225  uint8_t * tabStop;
226  bool cursorPastLastCol;
227  bool originMode;
228  GlyphOptions glyphOptions;
229  uint8_t characterSetIndex;
230  uint8_t characterSet[4];
231 };
232 
233 
234 enum KeypadMode {
235  Application, // DECKPAM
236  Numeric, // DECKPNM
237 };
238 
239 
240 struct EmuState {
241 
242  // Index of characterSet[], 0 = G0 (Standard) 1 = G1 (Alternate), 2 = G2, 3 = G3
243  uint8_t characterSetIndex;
244 
245  // 0 = DEC Special Character and Line Drawing 1 = United States (USASCII)
246  uint8_t characterSet[4];
247 
248  Color foregroundColor;
249  Color backgroundColor;
250 
251  // cursor position (topleft = 1,1)
252  int cursorX;
253  int cursorY;
254 
255  bool cursorPastLastCol;
256 
257  bool originMode;
258 
259  bool wraparound;
260 
261  // top and down scrolling regions (1 = first row)
262  int scrollingRegionTop;
263  int scrollingRegionDown;
264 
265  bool cursorEnabled;
266 
267  // true = blinking cursor, false = steady cursor
268  bool cursorBlinkingEnabled;
269 
270  // 0,1,2 = block 3,4 = underline 5,6 = bar
271  int cursorStyle;
272 
273  // column 1 at m_emuState.tabStop[0], column 2 at m_emuState.tabStop[1], etc... 0=no tab stop, 1 = tab stop
274  uint8_t * tabStop;
275 
276  // IRM (Insert Mode)
277  bool insertMode;
278 
279  // NLM (Automatic CR LF)
280  bool newLineMode;
281 
282  // DECSCLM (Smooth scroll)
283  // Smooth scroll is effective only when vertical sync refresh is enabled,
284  // hence must be VGAController.enableBackgroundPrimitiveExecution(true),
285  // that is the default.
286  bool smoothScroll;
287 
288  // DECKPAM (Keypad Application Mode)
289  // DECKPNM (Keypad Numeric Mode)
290  KeypadMode keypadMode;
291 
292  // DECCKM (Cursor Keys Mode)
293  bool cursorKeysMode;
294 
295  // DESSCL (1 = VT100 ... 5 = VT500)
296  int conformanceLevel;
297 
298  // two values allowed: 7 and 8
299  int ctrlBits;
300 
301  bool keyAutorepeat;
302 
303  bool allow132ColumnMode;
304 
305  bool reverseWraparoundMode;
306 
307  // DECBKM (false = BACKSPACE sends BS, false BACKSPACE sends DEL)
308  bool backarrowKeyMode;
309 
310  // DECANM (false = VT52 mode, true = ANSI mode)
311  bool ANSIMode;
312 
313  // VT52 Graphics Mode
314  bool VT52GraphicsMode;
315 };
316 
317 
318 
396 class TerminalClass : public Stream {
397 
398 public:
399 
405  void begin();
406 
412  void end();
413 
431  void connectSerialPort(HardwareSerial & serialPort, bool autoXONXOFF = true);
432 
446  void pollSerialPort();
447 
461  void connectLocally();
462 
470  void localWrite(uint8_t c);
471 
479  void localWrite(char const * str);
480 
494  void setLogStream(Stream & stream) { m_logStream = &stream; }
495 
496  void logFmt(const char * format, ...);
497  void log(const char * txt);
498  void log(char c);
499 
509  void loadFont(FontInfo const * font);
510 
524  void setBackgroundColor(Color color, bool setAsDefault = true);
525 
539  void setForegroundColor(Color color, bool setAsDefault = true);
540 
552  void clear();
553 
560  void flush(bool waitVSync);
561 
567  int getColumns() { return m_columns; }
568 
574  int getRows() { return m_rows; }
575 
581  void enableCursor(bool value);
582 
588  int availableForWrite();
589 
590 
593 
601  int available();
602 
610  int read();
611 
619  int peek();
620 
626  void flush();
627 
648  int write(const uint8_t * buffer, int size);
649 
659  size_t write(uint8_t c);
660 
661  using Print::write;
662 
663 
664 private:
665 
666  void reset();
667  void int_clear();
668  void clearMap(uint32_t * map);
669 
670  void freeFont();
671  void freeTabStops();
672  void freeGlyphsMap();
673 
674  void set132ColumnMode(bool value);
675 
676  bool moveUp();
677  bool moveDown();
678  void setCursorPos(int X, int Y);
679  int getAbsoluteRow(int Y);
680 
681  void int_setBackgroundColor(Color color);
682  void int_setForegroundColor(Color color);
683 
684  // tab stops
685  void nextTabStop();
686  void setTabStop(int column, bool set);
687  void resetTabStops();
688 
689  // scroll control
690  void scrollDown();
691  void scrollDownAt(int startingRow);
692  void scrollUp();
693  void scrollUpAt(int startingRow);
694  void setScrollingRegion(int top, int down, bool resetCursorPos = true);
695  void updateCanvasScrollingRegion();
696 
697  // multilevel save/restore cursor state
698  void saveCursorState();
699  void restoreCursorState();
700  void clearSavedCursorStates();
701 
702  void erase(int X1, int Y1, int X2, int Y2, char c, bool maintainDoubleWidth, bool selective);
703 
704  void consumeInputQueue();
705  void consumeESC();
706  void consumeCSI();
707  void consumeCSIQUOT(int * params, int paramsCount);
708  void consumeCSISPC(int * params, int paramsCount);
709  char consumeParamsAndGetCode(int * params, int * paramsCount, bool * questionMarkFound);
710  void consumeDECPrivateModes(int const * params, int paramsCount, char c);
711  void consumeDCS();
712  void execSGRParameters(int const * params, int paramsCount);
713  void consumeESCVT52();
714 
715  void execCtrlCode(char c);
716 
717  static void charsConsumerTask(void * pvParameters);
718  static void keyboardReaderTask(void * pvParameters);
719 
720  static void blinkTimerFunc(TimerHandle_t xTimer);
721  void blinkText();
722  bool enableBlinkingText(bool value);
723  void blinkCursor();
724  bool int_enableCursor(bool value);
725 
726  char getNextCode(bool processCtrlCodes);
727 
728  void setChar(char c);
729  GlyphOptions getGlyphOptionsAt(int X, int Y);
730 
731  void insertAt(int column, int row, int count);
732  void deleteAt(int column, int row, int count);
733 
734  void reverseVideo(bool value);
735 
736  void refresh();
737  void refresh(int X, int Y);
738  void refresh(int X1, int Y1, int X2, int Y2);
739  void beginRefresh();
740  void endRefresh();
741 
742  void setLineDoubleWidth(int row, int value);
743  int getCharWidthAt(int row);
744  int getColumnsAt(int row);
745 
746  void useAlternateScreenBuffer(bool value);
747 
748  void send(char c);
749  void send(char const * str);
750  void sendCSI();
751  void sendDCS();
752  void sendSS3();
753  void sendCursorKeyCode(char c);
754  void sendKeypadCursorKeyCode(char applicationCode, const char * numericCode);
755 
756  void ANSIDecodeVirtualKey(VirtualKey vk);
757  void VT52DecodeVirtualKey(VirtualKey vk);
758 
759  Stream * m_logStream;
760 
761  // characters, characters attributes and characters colors container
762  // you may also call this the "text screen buffer"
763  GlyphsBuffer m_glyphsBuffer;
764 
765  // used to implement alternate screen buffer
766  uint32_t * m_alternateMap;
767 
768  // true when m_alternateMap and m_glyphBuffer.map has been swapped
769  bool m_alternateScreenBuffer;
770 
771  // just to restore cursor X and Y pos when swapping screens (alternate screen)
772  int m_alternateCursorX;
773  int m_alternateCursorY;
774 
775  FontInfo m_font;
776 
777  PaintOptions m_paintOptions;
778  GlyphOptions m_glyphOptions;
779 
780  EmuState m_emuState;
781 
782  Color m_defaultForegroundColor;
783  Color m_defaultBackgroundColor;
784 
785  // states of cursor and blinking text before consumeInputQueue()
786  bool m_prevCursorEnabled;
787  bool m_prevBlinkingTextEnabled;
788 
789  // task that reads and processes incoming characters
790  TaskHandle_t m_charsConsumerTaskHandle;
791 
792  // task that reads keyboard input and send ANSI/VT100 codes to serial port
793  TaskHandle_t m_keyboardReaderTaskHandle;
794 
795  // true = cursor in reverse state (visible), false = cursor invisible
796  volatile bool m_cursorState;
797 
798  // timer used to blink
799  TimerHandle_t m_blinkTimer;
800  volatile SemaphoreHandle_t m_blinkTimerMutex;
801 
802  volatile bool m_blinkingTextVisible; // true = blinking text is currently visible
803  volatile bool m_blinkingTextEnabled;
804 
805  volatile int m_columns;
806  volatile int m_rows;
807 
808  // optional serial port
809  // data from serial port is processed and displayed
810  // keys from keyboard are processed and sent to serial port
811  HardwareSerial * m_serialPort;
812 
813  // contains characters to be processed (from write() calls)
814  QueueHandle_t m_inputQueue;
815 
816  // contains characters received and decoded from keyboard (or as replyed to ANSI-VT queries)
817  QueueHandle_t m_outputQueue;
818 
819  // linked list that contains saved cursor states (first item is the last added)
820  TerminalCursorState * m_savedCursorStateList;
821 
822  // a reset has been requested
823  bool m_resetRequested;
824 
825  bool m_autoXONOFF;
826  bool m_XOFF; // true = XOFF sent
827 
828  // used to implement m_emuState.keyAutorepeat
829  VirtualKey m_lastPressedKey;
830 
831 };
832 
833 
834 } // end of namespace
835 
836 
837 
838 extern fabgl::TerminalClass Terminal;
839 
840 
841 
842 #endif
void connectSerialPort(HardwareSerial &serialPort, bool autoXONXOFF=true)
Connect a remove host using the specified serial port.
Definition: terminal.cpp:132
void flush()
Wait for all codes sent to the display has been processed.
Definition: terminal.cpp:963
void pollSerialPort()
Pool the serial port for incoming data.
Definition: terminal.cpp:969
void clear()
Clear the screen.
Definition: terminal.cpp:415
VirtualKey
Represents each possible real or derived (SHIFT + real) key.
Definition: keyboard.h:86
This file contains fabgl::KeyboardClass definition and the Keyboard instance.
void localWrite(uint8_t c)
Inject keys into the keyboard queue.
Definition: terminal.cpp:916
An ANSI-VT100 compatible display terminal.
Definition: terminal.h:396
int available()
Get the number of codes available in the keyboard queue.
Definition: terminal.cpp:939
void setForegroundColor(Color color, bool setAsDefault=true)
Set the foreground color.
Definition: terminal.cpp:389
This file contains fabgl::CanvasClass definition and the related Canvas instance. ...
int getRows()
Return the number of lines.
Definition: terminal.h:574
int availableForWrite()
Return number of codes that the display input queue can still accept.
Definition: terminal.cpp:1054
void enableCursor(bool value)
Enable or disable cursor.
Definition: terminal.cpp:496
Definition: canvas.cpp:37
Color
This enum defines named colors.
Definition: vgacontroller.h:206
void begin()
Initialize the terminal.
Definition: terminal.cpp:84
Specifies various glyph painting options.
Definition: vgacontroller.h:293
void end()
Finalize the terminal.
Definition: terminal.cpp:221
int getColumns()
Return the number of columns.
Definition: terminal.h:567
void setBackgroundColor(Color color, bool setAsDefault=true)
Set the background color.
Definition: terminal.cpp:373
This file contains FabGL library configuration settings, like number of supported colors...
int peek()
Read a code from the keyboard without advancing to the next one.
Definition: terminal.cpp:957
int read()
Read codes from keyboard.
Definition: terminal.cpp:945
void loadFont(FontInfo const *font)
Set the font to use.
Definition: terminal.cpp:312
void setLogStream(Stream &stream)
Set the stream where to output debugging logs.
Definition: terminal.h:494
void connectLocally()
Permits using of terminal locally.
Definition: terminal.cpp:150
int write(const uint8_t *buffer, int size)
Send specified number of codes to the display.
Definition: terminal.cpp:1072
Specifies general paint options.
Definition: vgacontroller.h:332