Update Changes to GraphicsClient interface

[martins]

I'll use this post to list changes to the oapi::GraphicsClient class since the 2010-P1 (100830) release. Hopefully this list will make it easier for graphics client developers to keep up to date with current developments.

Beta 110824

• Added clbkBeginBltGroup and clbkEndBltGroup methods for grouping blitting calls to the same target
• Corresponding oapiBeginBltGroup and oapiEndBltGroup functions added to user space interface, so that the mechanism can be supported by addons.
• Currently only the new main menu implementation makes use of the new client functions

Client recompilation required: yes
Client source changes required: no, but recommended if the new mechanism can improve the client efficiency.

Next Beta
Graphics client:

• Added method clbkCreateSurfaceEx (DWORD w, DWORD h, DWORD attrib)
• Once I am finished with the core update, the old methods clbkCreateSurface (DWORD w, DWORD h) and clbkCreateTexture (DWORD w, DWORD h) will no longer be called.

Addon space:

• Added function oapiCreateSurfaceEx (int w, int h, DWORD attrib)
• Marked oapiCreateSurface (int w, int h) as obsolete. For backward compatibility, this will call oapiCreateSurfaceEx with attrib=OAPISURFACE_RENDERTARGET | OAPISURFACE_GDI | OAPISURFACE_SKETCHPAD
• Marked oapiCreateTexture (int w, int h) as obsolete. For backward compatibility, this will call oapiCreateSurfaceEx with attrib=OAPISURFACE_TEXTURE | OAPISURFACE_RENDERTARGET | OAPISURFACE_GDI | OAPISURFACE_SKETCHPAD
• Added VESSEL4 interface. For now, this contains the single method
  

  RegisterPanelArea (PANELHANDLE hPanel, int id, const RECT &pos, int texidx, const RECT &texpos, int draw_event, int mouse_event, int bkmode)

  This is essentially the same as the corresponding VESSEL3 version (except for the texidx parameter which had been missing in VESSEL3), but the main difference is that the draw_event parameter can contain the additional flags PANEL_REDRAW_GDI and PANEL_REDRAW_SKETCHPAD to request support for GDI and/or Sketchpad access during redraw events. For the VESSEL3 version, both flags are added automatically for backward compatibility.

 

[jarmonik]

• Once I am finished with the core update, the old methods clbkCreateSurface (DWORD w, DWORD h) and clbkCreateTexture (DWORD w, DWORD h) will no longer be called.
• Marked oapiCreateSurface (int w, int h) as obsolete. For backward compatibility, this will call oapiCreateSurfaceEx with attrib=OAPISURFACE_RENDERTARGET | OAPISURFACE_GDI | OAPISURFACE_SKETCHPAD
• Marked oapiCreateTexture (int w, int h) as obsolete. For backward compatibility, this will call oapiCreateSurfaceEx with attrib=OAPISURFACE_TEXTURE | OAPISURFACE_RENDERTARGET | OAPISURFACE_GDI | OAPISURFACE_SKETCHPAD

Hold on a second. Sorry, I didn't notice this post earlier. This will probably confuse the client even more than it is confused with the current implementation. It would be better to continue passing the calls from the oapiCreateSurface(int w, int h) and oapiCreateTexture(int w, int h) to the corresponding calls for the graphics client interface. This would let the client to know that the actual flags are unknown and the client must determine the use of the surface by it's own.

Marked oapiCreateSurface (int w, int h) as obsolete. For backward compatibility, this will call oapiCreateSurfaceEx with attrib=OAPISURFACE_RENDERTARGET | OAPISURFACE_GDI | OAPISURFACE_SKETCHPAD

These are not necessarily the right flags for the every surface created with the oapiCreateSurface(). Feeding a misleading information for the client doesn't make things any easier. There is some logic that applies in the use of oapiCreateSurface() and oapiCreateTexture() functions in addons they aren't used randomly. For the graphics client it is vital that it knowns how the surface was created exactly and from where the data is coming from. If the calls are rerouted to the clbkCreateSurfaceEx() some pieces of information will be lost in the process.