How this is going to work

After a great deal of discussion on the matter, Eugene has given me a final decision:

The engine is going to specify a Graphics::PixelFormat to the backend.

So here’s how this is going to work:

  • New Methods
    • Graphics::PixelFormat constructor, for convenience of engine developers (details to be determined)
    • OSystem::getBestFormat(void)
      • Returns a Graphics::PixelFormat describing the highest bitdepth supported by the backend (important for YUV games which will want to output in the highest quality)
    • OSystem::initFormat(Graphics::PixelFormat)
      • Set up the color format of the virtual screen in the gfxtransaction, to be applied on endGfxTransaction
    • Graphics::PixelFormat OSystem::getScreenFormat(void)
      • Returns a pixelformat describing the current color mode
    • CursorManager::pushCursorFormat(Graphics::PixelFormat)
      • Pushes a new cursor pixel format onto the stack, and set it in the backend.
    • CursorManager::popCursorFormat(void)
      • Pop a cursor pixel format from the stack, and restore the previous one to the backend.
      • If there is no previous format, the current screen format is used instead.
      • Unlike CursorManager::popCursorPalette, this must be called prior to CursorManager::popCursor
    • CursorManager::replaceCursorFormat(Graphics::PixelFormat)
      • Replace the current cursor pixel format on the stack.
      • If the stack is empty, the format is pushed instead.
      • These methods should be called whenever the equivalent *CursorPalette methods are called, to keep cursor rendering straight across color mode changes.
  • Changed functions/methods
    • initGraphics
      • Takes an optional pointer to a Graphics::PixelFormat struct
      • if pointer is null or not supplied, initializes using CLUT8 (standard 8-bit that everything already uses)
    • OSystem::endGFXTransaction
      • Must apply the color mode setup by initFormat
      • kTransactionPixelFormatNotSupported is included in the return value if color mode setup fails
  • TODO: new and changed class members.

The bitdepth initialization process will be as follows:

  • 8Bit paletted:
    1. Engine calls initGraphics (no changes are required on the engine side)
    2. initGraphics initializes a CLUT8 Graphics::PixelFormat, skips compatibility checking because all backends must support CLUT8 exactly they currently do
    3. initGraphics passes the CLUT8 PixelFormat to OSystem::initFormat
    4. Backend sees that the format matches the one that is currently set up, and ignores that part of the transaction
  • High or true color RGB:
    1. Engine initializes a Graphics::PixelFormat with the color format that the game uses (games which convert from YUV will query OSystem::getBestFormat to decide this)
    2. Engine passes this format to initGraphics
    3. initGraphics passes this format to OSystem::initFormat
    4. Backend sets up virtual screen format to be applied with transaction
    5. Backend attempts to initialize virtual screen with specified format and resolution, falls back to 8-bit and returns kTransactionPixelFormatNotSupported on failure.
    6. initGraphics checks transaction return for kTransactionPixelFormatNotSupported, and warns if encountered.
    7. Engine queries backend (using OSystem::getScreenFormat) to check the current color format
    8. Engine branches based on result:
      • Requested format
        1. Engine runs happily
      • CLUT8
        • If engine supports a 256 color fallback mode
          1. Engine falls back to 256 colors, and runs with only minor complaint
        • If engine does not support a 256 color fallback
          1. Engine displays error message that the system does not support its required format
          2. Engine returns with error (error code TBD).