libretro/scummvm
1
0
Fork 0
mirror of https://github.com/libretro/scummvm.git synced 2025-05-13 09:36:21 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

SCI32: Clean up GfxFrameout

Browse Source 
* Rewrap doxygen comments to 80 columns
* Swap public/private sections so public APIs come first
* Clarify comments where easily possible
This commit is contained in:
Colin Snover 2017-10-05 23:21:05 -05:00
parent c413030be3
commit f51b158f8c
3 changed files with 213 additions and 241 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
engines/sci/engine/kgraphics32.cpp
View File

@ -102,9 +102,9 @@ reg_t kBaseSetter32(EngineState *s, int argc, reg_t *argv) {
reg_t kSetNowSeen32(EngineState *s, int argc, reg_t *argv) {
const bool found = g_sci->_gfxFrameout->kernelSetNowSeen(argv[0]);
// NOTE: MGDX is assumed to use the older kSetNowSeen since it was
// released before SQ6, but this has not been verified since it cannot be
// disassembled at the moment (Phar Lap Windows-only release)
// MGDX is assumed to use the older kSetNowSeen since it was released before
// SQ6, but this has not been verified since it cannot be disassembled at
// the moment (Phar Lap Windows-only release)
// (See also getNowSeenRect)
if (getSciVersion() <= SCI_VERSION_2_1_EARLY ||
g_sci->getGameId() == GID_SQ6 ||

79
engines/sci/graphics/frameout.cpp
View File

@ -119,9 +119,9 @@ void GfxFrameout::run() {
ScreenItem::init();
GfxText32::init();
// NOTE: This happens in SCI::InitPlane in the actual engine,
// and is a background fill plane to ensure hidden planes
// (planes with a priority of -1) are never drawn
// This plane is created in SCI::InitPlane in SSCI, and is a background fill
// plane to ensure "hidden" planes (planes with negative priority) are never
// drawn
Plane *initPlane = new Plane(Common::Rect(_currentBuffer.scriptWidth, _currentBuffer.scriptHeight));
initPlane->_priority = 0;
_planes.add(initPlane);
@ -296,8 +296,8 @@ void GfxFrameout::kernelDeletePlane(const reg_t object) {
}
if (plane->_created) {
// NOTE: The original engine calls some `AbortPlane` function that
// just ends up doing this anyway so we skip the extra indirection
// SSCI calls some `AbortPlane` function that just ends up doing this
// anyway, so we skip the extra indirection
_planes.erase(plane);
} else {
plane->_created = 0;
@ -331,8 +331,8 @@ void GfxFrameout::kernelMovePlaneItems(const reg_t object, const int16 deltaX, c
for (ScreenItemList::iterator it = plane->_screenItemList.begin(); it != plane->_screenItemList.end(); ++it) {
ScreenItem &screenItem = **it;
// If object is a number, the screen item from the
// engine, not a script, and should be ignored
// If object is a number, the screen item from the engine, not a script,
// and should be ignored
if (screenItem._object.isNumber()) {
continue;
}
@ -365,14 +365,14 @@ void GfxFrameout::addPlane(Plane *plane) {
}
void GfxFrameout::updatePlane(Plane &plane) {
// NOTE: This assertion comes from SCI engine code.
// This assertion comes from SSCI
assert(_planes.findByObject(plane._object) == &plane);
Plane *visiblePlane = _visiblePlanes.findByObject(plane._object);
plane.sync(visiblePlane, _screenRect);
// NOTE: updateScreenRect was originally called a second time here,
// but it is already called at the end of the Plane::Update call
// in the original engine anyway.
// updateScreenRect was called a second time here in SSCI, but it is already
// called at the end of the sync call (also in SSCI) so there is no reason
// to do it again
_planes.sort();
}
@ -401,8 +401,8 @@ void GfxFrameout::frameOut(const bool shouldShowBits, const Common::Rect &eraseR
robotPlayer.doRobot();
}
// NOTE: The original engine allocated these as static arrays of 100
// pointers to ScreenItemList / RectList
// SSCI allocated these as static arrays of 100 pointers to
// ScreenItemList / RectList
ScreenItemListList screenItemLists;
EraseListList eraseLists;
@ -459,8 +459,8 @@ void GfxFrameout::palMorphFrameOut(const int8 *styleRanges, PlaneShowStyle *show
_showList.add(rect);
showBits();
// NOTE: The original engine allocated these as static arrays of 100
// pointers to ScreenItemList / RectList
// SSCI allocated these as static arrays of 100 pointers to
// ScreenItemList / RectList
ScreenItemListList screenItemLists;
EraseListList eraseLists;
@ -651,8 +651,7 @@ int splitRectsForRender(Common::Rect &middleRect, const Common::Rect &showRect,
return splitCount;
}
// NOTE: The third rectangle parameter is only ever given a non-empty rect
// by VMD code, via `frameOut`
// The third rectangle parameter is only ever passed by VMD code
void GfxFrameout::calcLists(ScreenItemListList &drawLists, EraseListList &eraseLists, const Common::Rect &eraseRect) {
RectList eraseList;
Common::Rect outRects[4];
@ -670,8 +669,8 @@ void GfxFrameout::calcLists(ScreenItemListList &drawLists, EraseListList &eraseL
const Plane *outerPlane = _planes[outerPlaneIndex];
const Plane *visiblePlane = _visiblePlanes.findByObject(outerPlane->_object);
// NOTE: SSCI only ever checks for kPlaneTypeTransparent here, even
// though kPlaneTypeTransparentPicture is also a transparent plane
// SSCI only ever checks for kPlaneTypeTransparent here, even though
// kPlaneTypeTransparentPicture is also a transparent plane
if (outerPlane->_type == kPlaneTypeTransparent) {
foundTransparentPlane = true;
}
@ -741,7 +740,6 @@ void GfxFrameout::calcLists(ScreenItemListList &drawLists, EraseListList &eraseL
}
}
// clean up deleted planes
if (deletedPlaneCount) {
for (int planeIndex = planeCount - 1; planeIndex >= 0; --planeIndex) {
Plane *plane = _planes[planeIndex];
@ -866,7 +864,7 @@ void GfxFrameout::calcLists(ScreenItemListList &drawLists, EraseListList &eraseL
}
}
// NOTE: SSCI only looks for kPlaneTypeTransparent, not
// SSCI really only looks for kPlaneTypeTransparent, not
// kPlaneTypeTransparentPicture
if (foundTransparentPlane) {
for (PlaneList::size_type planeIndex = 0; planeIndex < planeCount; ++planeIndex) {
@ -913,8 +911,6 @@ void GfxFrameout::drawScreenItemList(const DrawList &screenItemList) {
const DrawItem &drawItem = *screenItemList[i];
mergeToShowList(drawItem.rect, _showList, _overdrawThreshold);
const ScreenItem &screenItem = *drawItem.screenItem;
// TODO: Remove
// debug("Drawing item %04x:%04x to %d %d %d %d", PRINT_REG(screenItem._object), PRINT_RECT(drawItem.rect));
CelObj &celObj = *screenItem._celObj;
celObj.draw(_currentBuffer, screenItem, drawItem.rect, screenItem._mirrorX ^ celObj._mirrorX);
}
@ -986,9 +982,8 @@ void GfxFrameout::showBits() {
for (RectList::const_iterator rect = _showList.begin(); rect != _showList.end(); ++rect) {
Common::Rect rounded(**rect);
// NOTE: SCI engine used BR-inclusive rects so used slightly
// different masking here to ensure that the width of rects
// was always even.
// SSCI uses BR-inclusive rects so has slightly different masking here
// to ensure that the width of rects is always even
rounded.left &= ~1;
rounded.right = (rounded.right + 1) & ~1;
_cursor->gonnaPaint(rounded);
@ -998,9 +993,8 @@ void GfxFrameout::showBits() {
for (RectList::const_iterator rect = _showList.begin(); rect != _showList.end(); ++rect) {
Common::Rect rounded(**rect);
// NOTE: SCI engine used BR-inclusive rects so used slightly
// different masking here to ensure that the width of rects
// was always even.
// SSCI uses BR-inclusive rects so has slightly different masking here
// to ensure that the width of rects is always even
rounded.left &= ~1;
rounded.right = (rounded.right + 1) & ~1;
@ -1094,9 +1088,9 @@ void GfxFrameout::alterVmap(const Palette &palette1, const Palette &palette2, co
int8 styleRangeValue = styleRanges[currentValue];
if (styleRangeValue == -1 && styleRangeValue == style) {
currentValue = pixels[pixelIndex] = clut[currentValue];
// NOTE: In original engine this assignment happens outside of the
// condition, but if the branch is not followed the value is just
// going to be the same as it was before
// In SSCI this assignment happens outside of the condition, but if
// the branch is not followed the value is just going to be the same
// as it was before, so we do it here instead
styleRangeValue = styleRanges[currentValue];
}
@ -1110,7 +1104,7 @@ void GfxFrameout::alterVmap(const Palette &palette1, const Palette &palette2, co
}
void GfxFrameout::updateScreen(const int delta) {
// using OSystem::getMillis instead of Sci::getTickCount because these
// Using OSystem::getMillis instead of Sci::getTickCount here because these
// values need to be monotonically increasing for the duration of the
// GfxFrameout object or else the screen will stop updating
const uint32 now = g_system->getMillis() * 60 / 1000;
@ -1199,13 +1193,12 @@ reg_t GfxFrameout::kernelIsOnMe(const reg_t object, const Common::Point &positio
return make_reg(0, 0);
}
// NOTE: The original engine passed a copy of the ScreenItem into isOnMe
// as a hack around the fact that the screen items in `_visiblePlanes`
// did not have their `_celObj` pointers cleared when their CelInfo was
// updated by `Plane::decrementScreenItemArrayCounts`. We handle this
// this more intelligently by clearing `_celObj` in the copy assignment
// operator, which is only ever called by `decrementScreenItemArrayCounts`
// anyway.
// SSCI passed a copy of the ScreenItem into isOnMe as a hack around the
// fact that the screen items in `_visiblePlanes` did not have their
// `_celObj` pointers cleared when their CelInfo was updated by
// `Plane::decrementScreenItemArrayCounts`. We handle this this more
// intelligently by clearing `_celObj` in the copy assignment operator,
// which is only ever called by `decrementScreenItemArrayCounts` anyway.
return make_reg(0, isOnMe(*screenItem, *plane, position, checkPixel));
}
@ -1271,9 +1264,9 @@ bool GfxFrameout::getNowSeenRect(const reg_t screenItemObject, Common::Rect &res
const ScreenItem *screenItem = plane->_screenItemList.findByObject(screenItemObject);
if (screenItem == nullptr) {
// NOTE: MGDX is assumed to use the older getNowSeenRect since it was
// released before SQ6, but this has not been verified since it cannot
// be disassembled at the moment (Phar Lap Windows-only release)
// MGDX is assumed to use the older getNowSeenRect since it was released
// before SQ6, but this has not been verified since it cannot be
// disassembled at the moment (Phar Lap Windows-only release)
// (See also kSetNowSeen32)
if (getSciVersion() <= SCI_VERSION_2_1_EARLY ||
g_sci->getGameId() == GID_SQ6 ||

369
engines/sci/graphics/frameout.h
View File

@ -37,21 +37,11 @@ class GfxTransitions32;
struct PlaneShowStyle;
/**
* Frameout class, kFrameout and relevant functions for SCI32 games.
* Roughly equivalent to GraphicsMgr in the actual SCI engine.
* Frameout class, kFrameOut and relevant functions for SCI32 games.
* Roughly equivalent to GraphicsMgr in SSCI.
*/
class GfxFrameout {
friend class GfxTransitions32;
private:
GfxCursor32 *_cursor;
GfxPalette32 *_palette;
SegManager *_segMan;
/**
* Determines whether the current game should be rendered in
* high resolution.
*/
bool gameIsHiRes() const;
public:
GfxFrameout(SegManager *segMan, GfxPalette32 *palette, GfxTransitions32 *transitions, GfxCursor32 *cursor);
@ -62,12 +52,20 @@ public:
void clear();
void run();
private:
GfxCursor32 *_cursor;
GfxPalette32 *_palette;
GfxTransitions32 *_transitions;
SegManager *_segMan;
/**
* Determines whether the current game should be rendered in high
* resolution.
*/
bool gameIsHiRes() const;
#pragma mark -
#pragma mark Screen items
private:
void remapMarkRedraw();
bool getNowSeenRect(const reg_t screenItemObject, Common::Rect &result) const;
public:
/**
* Adds a screen item.
@ -100,39 +98,27 @@ public:
bool kernelSetNowSeen(const reg_t screenItemObject) const;
int16 kernelObjectIntersect(const reg_t object1, const reg_t object2) const;
private:
void remapMarkRedraw();
bool getNowSeenRect(const reg_t screenItemObject, Common::Rect &result) const;
#pragma mark -
#pragma mark Planes
private:
/**
* The list of planes (i.e. layers) that have been added
* to the screen.
*
* @note This field is on `GraphicsMgr.screen` in SCI
* engine.
*/
PlaneList _planes;
/**
* Updates an existing plane with properties from the
* given VM object.
*/
void updatePlane(Plane &plane);
public:
/**
* Creates and adds a new plane to the plane list. Ownership of the passed
* object is transferred to GfxFrameout.
*
* @note This method is on Screen in SCI engine, but it
* is only ever called on `GraphicsMgr.screen`.
* @note This method is on Screen in SSCI, but it is only ever called on
* `GraphicsMgr.screen`.
*/
void addPlane(Plane *plane);
/**
* Deletes a plane within the current plane list.
*
* @note This method is on Screen in SCI engine, but it
* is only ever called on `GraphicsMgr.screen`.
* @note This method is on Screen in SSCI, but it is only ever called on
* `GraphicsMgr.screen`.
*/
void deletePlane(Plane &plane);
@ -148,6 +134,20 @@ public:
void kernelMovePlaneItems(const reg_t object, const int16 deltaX, const int16 deltaY, const bool scrollPics);
int16 kernelGetHighPlanePri();
private:
/**
* The list of planes (i.e. layers) that will be rendered to the screen on
* the next call to `frameOut`.
*
* @note This field is on `GraphicsMgr.screen` in SSCI.
*/
PlaneList _planes;
/**
* Updates an existing plane with properties from the given VM object.
*/
void updatePlane(Plane &plane);
#pragma mark -
#pragma mark Pics
public:
@ -155,141 +155,6 @@ public:
#pragma mark -
#pragma mark Rendering
private:
/**
* The last time the hardware screen was updated.
*/
uint32 _lastScreenUpdateTick;
GfxTransitions32 *_transitions;
/**
* State tracker to provide more accurate 60fps
* video throttling.
*/
uint8 _throttleState;
/**
* The internal display pixel buffer. During frameOut,
* this buffer is drawn into according to the draw and
* erase rects calculated by `calcLists`, then drawn out
* to the hardware surface according to the `_showList`
* rects (which are also calculated by `calcLists`).
*/
Buffer _currentBuffer;
/**
* When true, a change to the remap zone in the palette
* has occurred and screen items with remap data need to
* be redrawn.
*/
bool _remapOccurred;
/**
* TODO: Document
* TODO: Depending upon if the engine ever modifies this
* rect, it may be stupid to store it separately instead
* of just getting width/height from GfxScreen.
*
* @note This field is on `GraphicsMgr.screen` in SCI
* engine.
*/
Common::Rect _screenRect;
/**
* A list of rectangles, in display coordinates, that
* represent portions of the internal screen buffer that
* should be drawn to the hardware display surface.
*
* @note This field is on `GraphicsMgr.screen` in SCI
* engine.
*/
RectList _showList;
/**
* The amount of extra overdraw that is acceptable when
* merging two show list rectangles together into a
* single larger rectangle.
*
* @note This field is on `GraphicsMgr.screen` in SCI
* engine.
*/
int _overdrawThreshold;
/**
* A list of planes that are currently drawn to the
* hardware display surface. Used to calculate
* differences in plane properties between the last
* frame and current frame.
*
* @note This field is on `GraphicsMgr.visibleScreen` in
* SCI engine.
*/
PlaneList _visiblePlanes;
/**
* Calculates the location and dimensions of dirty rects
* over the entire screen for rendering the next frame.
* The draw and erase lists in `drawLists` and
* `eraseLists` each represent one plane on the screen.
* The optional `eraseRect` argument allows a specific
* area of the screen to be erased.
*/
void calcLists(ScreenItemListList &drawLists, EraseListList &eraseLists, const Common::Rect &eraseRect = Common::Rect());
/**
* Erases the areas in the given erase list from the
* visible screen buffer by filling them with the color
* from the corresponding plane. This is an optimisation
* for colored-type planes only; other plane types have
* to be redrawn from pixel data.
*/
void drawEraseList(const RectList &eraseList, const Plane &plane);
/**
* Draws all screen items from the given draw list to
* the visible screen buffer.
*/
void drawScreenItemList(const DrawList &screenItemList);
/**
* Adds a new rectangle to the list of regions to write
* out to the hardware. The provided rect may be merged
* into an existing rectangle to reduce the number of
* blit operations.
*/
void mergeToShowList(const Common::Rect &drawRect, RectList &showList, const int overdrawThreshold);
/**
* Sends all dirty rects from the internal frame buffer to the backend,
* then updates the hardware screen.
*/
void showBits();
/**
* Validates whether the given palette index in the
* style range should copy a color from the next
* palette to the source palette during a palette
* morph operation.
*/
inline bool validZeroStyle(const uint8 style, const int i) const {
if (style != 0) {
return false;
}
// TODO: Cannot check Shivers or MGDX until those executables can be
// unwrapped
switch (g_sci->getGameId()) {
case GID_KQ7:
case GID_PHANTASMAGORIA:
case GID_SQ6:
return (i > 71 && i < 104);
break;
default:
return true;
}
}
public:
/**
* Updates the hardware screen, no more than once per tick.
@ -316,9 +181,9 @@ public:
bool _throttleKernelFrameOut;
/**
* Whether palMorphFrameOut should be used instead of
* frameOut for rendering. Used by kMorphOn to
* explicitly enable palMorphFrameOut for one frame.
* Whether `palMorphFrameOut` should be used instead of `frameOut` for
* rendering. Used by `kMorphOn` to explicitly enable `palMorphFrameOut` for
* one frame.
*/
bool _palMorphIsOn;
@ -329,16 +194,14 @@ public:
void kernelFrameOut(const bool showBits);
/**
* Throttles the engine as necessary to maintain
* 60fps output.
* Throttles the engine as necessary to maintain 60fps output.
*/
void throttle();
/**
* Updates the internal screen buffer for the next
* frame. If `shouldShowBits` is true, also sends the
* buffer to hardware. If `eraseRect` is non-empty,
* it is added to the erase list for this frame.
* Updates the internal screen buffer for the next frame. If
* `shouldShowBits` is true, also sends the buffer to hardware. If
* `eraseRect` is non-empty, it is added to the erase list for this frame.
*/
void frameOut(const bool shouldShowBits, const Common::Rect &eraseRect = Common::Rect());
@ -361,19 +224,18 @@ public:
#endif
/**
* Modifies the raw pixel data for the next frame with
* new palette indexes based on matched style ranges.
* Modifies the raw pixel data for the next frame with new palette indexes
* based on matched style ranges.
*/
void alterVmap(const Palette &palette1, const Palette &palette2, const int8 style, const int8 *const styleRanges);
// NOTE: This function is used within ScreenItem subsystem and assigned
// to various booleanish fields that seem to represent the state of the
// screen item (created, updated, deleted). In GK1/DOS, Phant1/m68k,
// SQ6/DOS, SQ6/Win, and Phant2/Win, this function simply returns 1. If
// you know of any game/environment where this function returns some
// value other than 1, or if you used to work at Sierra and can explain
// why this is a thing (and if anyone needs to care about it), please
// open a ticket!!
// This function is used within ScreenItem subsystem and assigned to various
// booleanish fields that seem to represent the state of the screen item
// (created, updated, deleted). In GK1/DOS, Phant1/m68k, SQ6/DOS, SQ6/Win,
// and Phant2/Win, this function simply returns 1. If you know of any
// game/environment where this function returns some value other than 1, or
// if you used to work at Sierra and can explain why this is a thing (and if
// anyone needs to care about it), please open a ticket!!
inline int getScreenCount() const {
return 1;
};
@ -383,8 +245,128 @@ public:
*/
void shakeScreen(const int16 numShakes, const ShakeDirection direction);
private:
/**
* The last time the hardware screen was updated.
*/
uint32 _lastScreenUpdateTick;
/**
* State tracker to provide more accurate 60fps video throttling.
*/
uint8 _throttleState;
/**
* The internal display pixel buffer. During `frameOut`, this buffer is
* drawn into according to the draw and erase rects calculated by
* `calcLists`, then drawn out to the hardware surface according to the
* `_showList` rects (which are also calculated by `calcLists`).
*/
Buffer _currentBuffer;
/**
* When true, a change to the remap zone in the palette has occurred and
* screen items with remap data need to be redrawn.
*/
bool _remapOccurred;
/**
* The dimensions of the output buffer, in display coordinates.
*
* @note This field is on `GraphicsMgr.screen` in SSCI.
*/
Common::Rect _screenRect;
/**
* A list of rectangles, in screen coordinates, that represent portions of
* the internal screen buffer that are dirty and should be drawn to the
* hardware display surface.
*
* @note This field is on `GraphicsMgr.screen` in SSCI.
*/
RectList _showList;
/**
* The amount of extra overdraw that is acceptable when merging two show
* list rectangles together into a single larger rectangle.
*
* @note This field is on `GraphicsMgr.screen` in SSCI.
*/
int _overdrawThreshold;
/**
* The list of planes that are currently drawn to the hardware display
* surface. Used to calculate differences in plane properties between the
* last frame and current frame.
*
* @note This field is on `GraphicsMgr.visibleScreen` in SSCI.
*/
PlaneList _visiblePlanes;
/**
* Calculates the location and dimensions of dirty rects over the entire
* screen for rendering the next frame. The draw and erase lists in
* `drawLists` and `eraseLists` each represent one plane on the screen.
* The optional `eraseRect` argument allows a specific area of the screen to
* be explicitly erased.
*/
void calcLists(ScreenItemListList &drawLists, EraseListList &eraseLists, const Common::Rect &eraseRect = Common::Rect());
/**
* Erases the areas in the given erase list from the visible screen buffer
* by filling them with the color from the corresponding plane. This is an
* optimisation for colored-type planes only; other plane types have to be
* redrawn from pixel data.
*/
void drawEraseList(const RectList &eraseList, const Plane &plane);
/**
* Draws all screen items from the given draw list to the visible screen
* buffer.
*/
void drawScreenItemList(const DrawList &screenItemList);
/**
* Adds a new rectangle to the list of regions to write out to the hardware.
* The provided rect may be merged into an existing rectangle to reduce the
* number of blit operations.
*/
void mergeToShowList(const Common::Rect &drawRect, RectList &showList, const int overdrawThreshold);
/**
* Sends all dirty rects from the internal frame buffer to the backend, then
* updates the hardware screen.
*/
void showBits();
/**
* Validates whether the given palette index in the style range should copy
* a color from the next palette to the source palette during a palette
* morph operation.
*/
inline bool validZeroStyle(const uint8 style, const int i) const {
if (style != 0) {
return false;
}
// TODO: Cannot check Shivers or MGDX until those executables can be
// unwrapped
switch (g_sci->getGameId()) {
case GID_KQ7:
case GID_PHANTASMAGORIA:
case GID_SQ6:
return (i > 71 && i < 104);
break;
default:
return true;
}
}
#pragma mark -
#pragma mark Mouse cursor
public:
reg_t kernelIsOnMe(const reg_t object, const Common::Point &position, const bool checkPixel) const;
private:
void updateMousePositionForRendering() const {
// In SSCI, mouse events were received via hardware interrupt, so the
@ -398,14 +380,11 @@ private:
}
/**
* Determines whether or not the point given by
* `position` is inside of the given screen item.
* Determines whether or not the point given by `position` is inside of the
* given screen item.
*/
bool isOnMe(const ScreenItem &screenItem, const Plane &plane, const Common::Point &position, const bool checkPixel) const;
public:
reg_t kernelIsOnMe(const reg_t object, const Common::Point &position, const bool checkPixel) const;
#pragma mark -
#pragma mark Debugging
public: