vgabasecontroller.h

Go to the documentation of this file.

/*
  Created by Fabrizio Di Vittorio (fdivitto2013@gmail.com) - <http://www.fabgl.com>
  Copyright (c) 2019-2022 Fabrizio Di Vittorio.
  All rights reserved.
 
 
* Please contact fdivitto2013@gmail.com if you need a commercial license.
 
 
* This library and related software is available under GPL v3.
 
  FabGL is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
 
  FabGL is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with FabGL.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 
#pragma once
 
 
 
#include <stdint.h>
#include <stddef.h>
#include <atomic>
 
#include "driver/gpio.h"
 
#include "freertos/FreeRTOS.h"
#include "freertos/queue.h"
 
#include "fabglconf.h"
#include "fabutils.h"
#include "devdrivers/swgenerator.h"
#include "displaycontroller.h"
 
 
 
 
#define VGA_RED_BIT    0
#define VGA_GREEN_BIT  2
#define VGA_BLUE_BIT   4
#define VGA_HSYNC_BIT  6
#define VGA_VSYNC_BIT  7
 
#define VGA_SYNC_MASK  ((1 << VGA_HSYNC_BIT) | (1 << VGA_VSYNC_BIT))
 
 
// pixel 0 = byte 2, pixel 1 = byte 3, pixel 2 = byte 0, pixel 3 = byte 1 :
// pixel : 0  1  2  3  4  5  6  7  8  9 10 11 ...etc...
// byte  : 2  3  0  1  6  7  4  5 10 11  8  9 ...etc...
// dword : 0           1           2          ...etc...
// Thanks to https://github.com/paulscottrobson for the new macro. Before was: (row[((X) & 0xFFFC) + ((2 + (X)) & 3)])
#define VGA_PIXELINROW(row, X)   (row[(X) ^ 2])
 
// requires variables: m_viewPort
#define VGA_PIXEL(X, Y)          VGA_PIXELINROW(m_viewPort[(Y)], X)
#define VGA_INVERT_PIXEL(X, Y)   { auto px = &VGA_PIXEL((X), (Y)); *px = ~(*px ^ VGA_SYNC_MASK); }
 
 
 
namespace fabgl {
 
 
 
#if FABGLIB_VGAXCONTROLLER_PERFORMANCE_CHECK
  extern volatile uint64_t s_vgapalctrlcycles;
#endif
 
 
 
enum VGAScanStart {
  FrontPorch,   
  Sync,         
  BackPorch,    
  VisibleArea   
};
 
 
struct VGATimings {
  char          label[22];       
  int           frequency;       
  int16_t       HVisibleArea;    
  int16_t       HFrontPorch;     
  int16_t       HSyncPulse;      
  int16_t       HBackPorch;      
  int16_t       VVisibleArea;    
  int16_t       VFrontPorch;     
  int16_t       VSyncPulse;      
  int16_t       VBackPorch;      
  char          HSyncLogic;      
  char          VSyncLogic;      
  uint8_t       scanCount;       
  uint8_t       multiScanBlack;  
  VGAScanStart  HStartingBlock;  
};
 
 
 
class VGABaseController : public GenericBitmappedDisplayController {
 
public:
 
  VGABaseController();
 
  // unwanted methods
  VGABaseController(VGABaseController const&) = delete;
  void operator=(VGABaseController const&)    = delete;
 
  void begin(gpio_num_t redGPIO, gpio_num_t greenGPIO, gpio_num_t blueGPIO, gpio_num_t HSyncGPIO, gpio_num_t VSyncGPIO);
 
  void begin(gpio_num_t red1GPIO, gpio_num_t red0GPIO, gpio_num_t green1GPIO, gpio_num_t green0GPIO, gpio_num_t blue1GPIO, gpio_num_t blue0GPIO, gpio_num_t HSyncGPIO, gpio_num_t VSyncGPIO);
 
  void begin();
 
  virtual void end();
 
  static bool convertModelineToTimings(char const * modeline, VGATimings * timings);
 
  // abstract method of BitmappedDisplayController
  virtual void suspendBackgroundPrimitiveExecution();
 
  // abstract method of BitmappedDisplayController
  virtual void resumeBackgroundPrimitiveExecution();
 
  void setResolution(char const * modeline, int viewPortWidth = -1, int viewPortHeight = -1, bool doubleBuffered = false);
 
  virtual void setResolution(VGATimings const& timings, int viewPortWidth = -1, int viewPortHeight = -1, bool doubleBuffered = false);
 
  int getViewPortCol()                             { return m_viewPortCol; }
 
  int getViewPortRow()                             { return m_viewPortRow; }
 
  void moveScreen(int offsetX, int offsetY);
 
  void shrinkScreen(int shrinkX, int shrinkY);
 
  VGATimings * getResolutionTimings()             { return &m_timings; }
 
  uint8_t getBitsPerChannel()                     { return m_bitsPerChannel; }
 
  virtual int colorsCount()                       { return 1 << (3 * m_bitsPerChannel); }
 
  uint8_t * getScanline(int y)                    { return (uint8_t*) m_viewPort[y]; }
 
  uint8_t createRawPixel(RGB222 rgb)             { return preparePixel(rgb); }
 
  uint8_t createBlankRawPixel()                  { return m_HVSync; }
 
 
 
protected:
 
  static void setupGPIO(gpio_num_t gpio, int bit, gpio_mode_t mode);
 
  void startGPIOStream();
 
  void freeBuffers();
 
  virtual void freeViewPort();
 
  virtual void init();
 
  bool setDMABuffersCount(int buffersCount);
 
  uint8_t packHVSync(bool HSync, bool VSync);
 
  uint8_t inline __attribute__((always_inline)) preparePixel(RGB222 rgb) { return m_HVSync | (rgb.B << VGA_BLUE_BIT) | (rgb.G << VGA_GREEN_BIT) | (rgb.R << VGA_RED_BIT); }
 
  uint8_t preparePixelWithSync(RGB222 rgb, bool HSync, bool VSync);
 
  void fillVertBuffers(int offsetY);
 
  void fillHorizBuffers(int offsetX);
 
  int fill(uint8_t volatile * buffer, int startPos, int length, uint8_t red, uint8_t green, uint8_t blue, bool hsync, bool vsync);
 
  int calcRequiredDMABuffersCount(int viewPortHeight);
 
  bool isMultiScanBlackLine(int scan);
 
  void setDMABufferBlank(int index, void volatile * address, int length, int scan, bool isStartOfVertFrontPorch);
  void setDMABufferView(int index, int row, int scan, volatile uint8_t * * viewPort, bool onVisibleDMA);
  void setDMABufferView(int index, int row, int scan, bool isStartOfVertFrontPorch);
 
  virtual void onSetupDMABuffer(lldesc_t volatile * buffer, bool isStartOfVertFrontPorch, int scan, bool isVisible, int visibleRow) = 0;
 
  void volatile * getDMABuffer(int index, int * length);
 
  void allocateViewPort(uint32_t allocCaps, int rowlen);
  virtual void allocateViewPort() = 0;
  virtual void checkViewPortSize() { };
 
  // abstract method of BitmappedDisplayController
  virtual void swapBuffers();
 
 
  // when double buffer is enabled the "drawing" view port is always m_viewPort, while the "visible" view port is always m_viewPortVisible
  // when double buffer is not enabled then m_viewPort = m_viewPortVisible
  volatile uint8_t * *   m_viewPort;
  volatile uint8_t * *   m_viewPortVisible;
 
  // true: double buffering is implemented in DMA
  bool                   m_doubleBufferOverDMA;
 
  volatile int           m_primitiveProcessingSuspended;             // 0 = enabled, >0 suspended
 
  intr_handle_t          m_isr_handle;
 
  VGATimings             m_timings;
  int16_t                m_HLineSize;
 
  volatile int16_t       m_viewPortCol;
  volatile int16_t       m_viewPortRow;
 
  // contains H and V signals for visible line
  volatile uint8_t       m_HVSync;
 
 
private:
 
 
  // bits per channel on VGA output
  // 1 = 8 colors, 2 = 64 colors, set by begin()
  int                    m_bitsPerChannel;
 
  GPIOStream             m_GPIOStream;
 
  lldesc_t volatile *    m_DMABuffers;
  int                    m_DMABuffersCount;
 
  // when double buffer is enabled at DMA level the running DMA buffer is always m_DMABuffersVisible
  // when double buffer is not enabled then m_DMABuffers = m_DMABuffersVisible
  lldesc_t volatile *    m_DMABuffersHead;
  lldesc_t volatile *    m_DMABuffersVisible;
 
  // These buffers contains a full line, with FrontPorch, Sync, BackPorch and blank visible area, in the
  // order specified by timings.HStartingBlock
  volatile uint8_t *     m_HBlankLine_withVSync;
  volatile uint8_t *     m_HBlankLine;
 
  uint8_t * *            m_viewPortMemoryPool;  // array ends with nullptr
 
  int16_t                m_rawFrameHeight;
 
};
 
 
 
 
 
 
 
 
} // end of namespace