retroviw.h

Go to the documentation of this file.

 
#ifndef RETROVIW_H
#define RETROVIW_H

 
#ifndef RETROFLAT_VIEWPORT_TRACE_LVL
#  define RETROFLAT_VIEWPORT_TRACE_LVL 0
#endif /* !RETROFLAT_VIEWPORT_TRACE_LVL */

#define RETROFLAT_VIEWPORT_FLAG_FULLSCREEN 0x01

struct RETROFLAT_VIEWPORT {
   uint8_t flags;
   retroflat_pxxy_t screen_x;
   retroflat_pxxy_t screen_y;
   retroflat_pxxy_t world_x;
   retroflat_pxxy_t world_y;
   retroflat_pxxy_t world_w;
   retroflat_pxxy_t world_h;
   retroflat_pxxy_t screen_w;
   retroflat_pxxy_t screen_h;
   retroflat_pxxy_t screen_w_remainder;
   retroflat_pxxy_t screen_h_remainder;
   int16_t screen_tile_w;
   int16_t screen_tile_h;
   int16_t world_tile_x;
   int16_t world_tile_y;
   int16_t world_tile_w;
   int16_t world_tile_h;
#ifndef RETROFLAT_NO_VIEWPORT_REFRESH
   MAUG_MHANDLE refresh_grid_h;
   retroflat_tile_t* refresh_grid;
#endif /* !RETROFLAT_NO_VIEWPORT_REFRESH */
};
 
#ifndef DOCUMENTATION
 
#  define retroflat_viewport_world_x_generic() \
   (g_retroflat_state->viewport.world_x)
 
#  define retroflat_viewport_world_y_generic() \
   (g_retroflat_state->viewport.world_y)
 
#  define retroflat_viewport_world_tile_x_generic() \
   (g_retroflat_state->viewport.world_tile_x)
 
#  define retroflat_viewport_world_tile_y_generic() \
   (g_retroflat_state->viewport.world_tile_y)
 
#  define retroflat_viewport_world_tile_w_generic() \
   (g_retroflat_state->viewport.world_tile_w)
 
#  define retroflat_viewport_world_tile_h_generic() \
   (g_retroflat_state->viewport.world_tile_h)
 
#  define retroflat_viewport_world_w_generic() \
   (g_retroflat_state->viewport.world_w)
 
#  define retroflat_viewport_world_h_generic() \
   (g_retroflat_state->viewport.world_h)
 
#  define retroflat_viewport_screen_tile_w_generic() \
   (g_retroflat_state->viewport.screen_tile_w)
 
#  define retroflat_viewport_screen_tile_h_generic() \
   (g_retroflat_state->viewport.screen_tile_h)
 
#  define retroflat_viewport_screen_w_generic() \
   (g_retroflat_state->viewport.screen_w)
 
#  define retroflat_viewport_screen_h_generic() \
   (g_retroflat_state->viewport.screen_h)
 
#  define retroflat_viewport_screen_w_remainder_generic() \
   (g_retroflat_state->viewport.screen_w_remainder)
 
#  define retroflat_viewport_screen_h_remainder_generic() \
   (g_retroflat_state->viewport.screen_h_remainder)
 
#  define retroflat_viewport_set_world_generic( w, h ) \
   debug_printf( 1, "setting viewport world size to %d x %d...", \
      (int16_t)(w), (int16_t)(h) ); \
   (g_retroflat_state->viewport.world_w) = (w); \
   (g_retroflat_state->viewport.world_h) = (h); \
   (g_retroflat_state->viewport.world_tile_w) = (w) / RETROFLAT_TILE_W; \
   (g_retroflat_state->viewport.world_tile_h) = (h) / RETROFLAT_TILE_H;
 
#  define retroflat_viewport_screen_x_generic( world_x ) \
   (g_retroflat_state->viewport.screen_x + \
      ((world_x) - retroflat_viewport_world_x()))
 
#  define retroflat_viewport_screen_y_generic( world_y ) \
   (g_retroflat_state->viewport.screen_y + \
      ((world_y) - retroflat_viewport_world_y()))
 
#  define retroflat_viewport_screen_get_x_generic() \
   (g_retroflat_state->viewport.screen_x)
 
#  define retroflat_viewport_screen_get_y_generic() \
   (g_retroflat_state->viewport.screen_y)
 
#define retroflat_viewport_grid_tile( x_tile, y_tile ) \
   (g_retroflat_state->viewport.refresh_grid[ \
      ((y_tile) * (g_retroflat_state->viewport.screen_tile_w + 2)) + \
            (x_tile)])
 
void retroflat_viewport_set_world_pos_generic(
   retroflat_pxxy_t x, retroflat_pxxy_t y );
 
MERROR_RETVAL retroflat_viewport_set_refresh_generic(
   retroflat_pxxy_t x_px, retroflat_pxxy_t y_px, retroflat_tile_t tid );
 
uint8_t retroflat_viewport_move_x_generic( retroflat_pxxy_t x );
 
uint8_t retroflat_viewport_move_y_generic( retroflat_pxxy_t y );
 
MERROR_RETVAL retroflat_viewport_set_pos_size_generic(
   retroflat_pxxy_t x_px, retroflat_pxxy_t y_px,
   retroflat_pxxy_t w_px,  retroflat_pxxy_t h_px );
 
#  ifndef RETROFLAT_NO_VIEWPORT_REFRESH
uint8_t retroflat_viewport_tile_is_stale(
   int x_tile, int y_tile, retroflat_tile_t tile_id );
#  endif /* !RETROFLAT_NO_VIEWPORT_REFRESH */
 
#endif /* !DOCUMENTATION */

uint8_t retroflat_viewport_focus(
   retroflat_pxxy_t x1, retroflat_pxxy_t y1,
   retroflat_pxxy_t range, retroflat_pxxy_t speed );

MERROR_RETVAL retroflat_viewport_trim_px(
   struct RETROFLAT_BITMAP* bitmap,
   int16_t instance,
   retroflat_pxxy_t* s_x, retroflat_pxxy_t* s_y,
   retroflat_pxxy_t* d_x, retroflat_pxxy_t* d_y,
   retroflat_pxxy_t* w, retroflat_pxxy_t* h );

MERROR_RETVAL retroflat_viewport_clear_refresh( retroflat_pxxy_t y_max );

MERROR_RETVAL retroflat_viewport_shift_viewport_x( int8_t shift );

MERROR_RETVAL retroflat_viewport_shift_viewport_y( int8_t shift );
 
#ifdef RETROFLAT_VIEWPORT_TRACE_CONSTRAIN
 
#  define retroflat_viewport_constrain_px( x, y, bmp, retact ) \
      if( \
         x >= retroflat_bitmap_w( bmp ) || y >= retroflat_bitmap_h( bmp ) || \
         0 > x || 0 > y \
      ) { \
         error_printf( "attempted draw at %d, %d, out of bounds %d x %d", \
            x, y, retroflat_bitmap_w( bmp ), retroflat_bitmap_h( bmp ) ); \
         retact; \
      }
 
#else

#  define retroflat_viewport_constrain_px( x, y, bmp, retact ) \
      if( \
         x >= retroflat_bitmap_w( bmp ) || y >= retroflat_bitmap_h( bmp ) || \
         0 > x || 0 > y \
      ) { \
         retact; \
      }
 
#endif /* RETROFLAT_TRACE_CONSTRAIN */
 
#if defined( RETROFLAT_SOFT_VIEWPORT ) || defined( DOCUMENTATION )
 
#  define retroflat_viewport_world_tile_x() \
      retroflat_viewport_world_tile_x_generic()
 
#  define retroflat_viewport_world_tile_y() \
      retroflat_viewport_world_tile_y_generic()
 
#  define retroflat_viewport_world_tile_w() \
      retroflat_viewport_world_tile_w_generic()
 
#  define retroflat_viewport_world_tile_h() \
      retroflat_viewport_world_tile_h_generic()
#  define retroflat_viewport_world_x() retroflat_viewport_world_x_generic()

#  define retroflat_viewport_world_y() retroflat_viewport_world_y_generic()

#  define retroflat_viewport_world_w() \
   retroflat_viewport_world_w_generic()

#  define retroflat_viewport_world_h() \
   retroflat_viewport_world_h_generic()

#  define retroflat_viewport_screen_tile_w() \
   retroflat_viewport_screen_tile_w_generic()

#  define retroflat_viewport_screen_tile_h() \
   retroflat_viewport_screen_tile_h_generic()

#  define retroflat_viewport_screen_w() \
   retroflat_viewport_screen_w_generic()

#  define retroflat_viewport_screen_h() \
   retroflat_viewport_screen_h_generic()

#  define retroflat_viewport_screen_w_remainder() \
   retroflat_viewport_screen_w_remainder_generic()

#  define retroflat_viewport_screen_h_remainder() \
   retroflat_viewport_screen_h_remainder_generic()

#  define retroflat_viewport_set_world( w, h ) \
   retroflat_viewport_set_world_generic( w, h )

#  define retroflat_viewport_set_world_pos( x, y ) \
   retroflat_viewport_set_world_pos_generic( x, y )

#  define retroflat_viewport_set_pos_size( x_px, y_px, w_px, h_px ) \
   retroflat_viewport_set_pos_size_generic( x_px, y_px, w_px, h_px )

#  define retroflat_viewport_screen_x( world_x ) \
   retroflat_viewport_screen_x_generic( world_x )

#  define retroflat_viewport_screen_y( world_y ) \
      retroflat_viewport_screen_y_generic( world_y )

#  define retroflat_viewport_screen_get_x() \
      retroflat_viewport_screen_get_x_generic()

#  define retroflat_viewport_screen_get_y() \
      retroflat_viewport_screen_get_y_generic()

#  define retroflat_viewport_move_x( x ) \
      retroflat_viewport_move_x_generic( x )

#  define retroflat_viewport_move_y( y ) \
      retroflat_viewport_move_y_generic( y )
 
#  define retroflat_viewport_hw_border_x() (0)
 
#  define retroflat_viewport_hw_border_y() (0)
 
#endif /* RETROFLAT_SOFT_VIEWPORT || DOCUMENTATION */
 
#ifndef RETROFLAT_NO_VIEWPORT_REFRESH

#  define retroflat_viewport_lock_refresh() \
   if( NULL == g_retroflat_state->viewport.refresh_grid ) { \
      maug_mlock( \
         g_retroflat_state->viewport.refresh_grid_h, \
         g_retroflat_state->viewport.refresh_grid ); \
      maug_cleanup_if_null_lock( retroflat_tile_t*, \
         g_retroflat_state->viewport.refresh_grid ); \
   }

#  define retroflat_viewport_unlock_refresh() \
   if( NULL != g_retroflat_state->viewport.refresh_grid ) { \
      maug_munlock( \
         g_retroflat_state->viewport.refresh_grid_h, \
         g_retroflat_state->viewport.refresh_grid ); \
   }

#  define retroflat_viewport_set_refresh( x, y, tid ) \
   retroflat_viewport_set_refresh_generic( x, y, tid )
 
#endif /* !RETROFLAT_NO_VIEWPORT_REFRESH */
 /* maug_retroflt_viewport */
 /* maug_retroflt */
 
#elif defined( RETROVIW_C )
 
void retroflat_viewport_set_world_pos_generic(
   retroflat_pxxy_t x, retroflat_pxxy_t y
) {
   int x_tile = (x >> RETROFLAT_TILE_W_BITS);
   int y_tile = (y >> RETROFLAT_TILE_H_BITS);
#if RETROFLAT_VIEWPORT_TRACE_LVL > 0
   debug_printf(
      RETROFLAT_VIEWPORT_TRACE_LVL,
      "setting viewport world pos to %d, %d (tile %d, %d)...",
      x, y, x_tile, y_tile );
#endif /* RETROFLAT_VIEWPORT_TRACE_LVL */
   g_retroflat_state->viewport.world_x = x;
   g_retroflat_state->viewport.world_y = y;
   g_retroflat_state->viewport.world_tile_x = x_tile;
   g_retroflat_state->viewport.world_tile_y = y_tile;
}
 
/* === */
 
#ifndef RETROFLAT_NO_VIEWPORT_REFRESH
 
MERROR_RETVAL retroflat_viewport_set_refresh_generic(
   retroflat_pxxy_t x_px, retroflat_pxxy_t y_px, retroflat_tile_t tid
) {
   int x_tile = 0;
   int y_tile = 0;
 
   /* Add +1 tile to make off-screen "-1" tile positive. */
   x_tile = x_px / RETROFLAT_TILE_W;
   y_tile = y_px / RETROFLAT_TILE_H;
 
   if(
      RETROFLAT_STATE_FLAG_HWSCROLLING ==
      (RETROFLAT_STATE_FLAG_HWSCROLLING & g_retroflat_state->retroflat_flags) &&
      RETROFLAT_VIEWPORT_FLAG_FULLSCREEN ==
      (RETROFLAT_VIEWPORT_FLAG_FULLSCREEN & g_retroflat_state->viewport.flags)
   ) {
      /*
      x_tile++;
      y_tile++;
      */
   }
 
#if RETROFLAT_VIEWPORT_GRID_TRACE_LVL > 0
   debug_printf( RETROFLAT_VIEWPORT_GRID_TRACE_LVL,
      "setting x_tile: %d, y_tile: %d (%d, %d) to: %d",
      x_tile, y_tile, x_px, y_px, tid );
#endif /* RETROFLAT_VIEWPORT_GRID_TRACE_LVL */
 
   assert( NULL != g_retroflat_state->viewport.refresh_grid );
   if(
      /* Expand the range by -1 to account for just off-screen tile. */
      0 > x_tile || 0 > y_tile ||
      g_retroflat_state->viewport.screen_tile_w + 2 <= x_tile ||
      g_retroflat_state->viewport.screen_tile_h + 2 <= y_tile
   ) {
#if RETROFLAT_VIEWPORT_TRACE_LVL > 0
      error_printf( "invalid viewport refresh coord: %d, %d", x_tile, y_tile );
      debug_printf( RETROFLAT_VIEWPORT_TRACE_LVL,
         "viewport is %dx%d tiles!",
         g_retroflat_state->viewport.screen_tile_w + 2,
         g_retroflat_state->viewport.screen_tile_h + 2 );
#endif /* RETROFLAT_VIEWPORT_TRACE_LVL */
      return MERROR_GUI;
   }
 
   retroflat_viewport_grid_tile( x_tile, y_tile ) = tid;
 
   return MERROR_OK;
}
 
/* === */
 
#endif /* RETROFLAT_NO_VIEWPORT_REFRESH */
 
uint8_t retroflat_viewport_move_x_generic( retroflat_pxxy_t x ) {
   retroflat_pxxy_t new_world_x = g_retroflat_state->viewport.world_x + x;
 
   /* Keep the viewport in the world arena. */
   if(
      0 <= new_world_x &&
      g_retroflat_state->viewport.world_w >= new_world_x +
         g_retroflat_state->viewport.screen_w
   ) {
      g_retroflat_state->viewport.world_x += x;
      g_retroflat_state->viewport.world_tile_x =
         g_retroflat_state->viewport.world_x >> RETROFLAT_TILE_W_BITS;
      return 1;
   }
 
   return 0;
}
 
/* === */
 
uint8_t retroflat_viewport_move_y_generic( retroflat_pxxy_t y ) {
   retroflat_pxxy_t new_world_y = g_retroflat_state->viewport.world_y + y;
 
   /* Keep the viewport in the world arena. */
   if(
      0 <= new_world_y &&
      g_retroflat_state->viewport.world_h >= new_world_y +
         g_retroflat_state->viewport.screen_h
   ) {
      g_retroflat_state->viewport.world_y += y;
      g_retroflat_state->viewport.world_tile_y =
         g_retroflat_state->viewport.world_y >> RETROFLAT_TILE_H_BITS;
      return 1;
   }
 
   return 0;
}
 
/* === */
 
uint8_t retroflat_viewport_focus(
   retroflat_pxxy_t x1, retroflat_pxxy_t y1,
   retroflat_pxxy_t range, retroflat_pxxy_t speed
) {
   uint8_t moved = 0,
      new_moved = 0;
   int16_t new_pt = 0;
 
   /* Test if the screen is scrolling east/west. */
   new_pt = x1 - retroflat_viewport_world_x();
   if( new_pt > (retroflat_screen_w() >> 1) + range ) {
      new_moved = retroflat_viewport_move_x(
         gc_retroflat_offsets8_x[RETROFLAT_DIR8_EAST] * speed );
      if( !moved && new_moved ) {
         moved = new_moved;
      }
   } else if( new_pt < (retroflat_screen_w() >> 1) - range ) {
      new_moved = retroflat_viewport_move_x(
         gc_retroflat_offsets8_x[RETROFLAT_DIR8_WEST] * speed );
      if( !moved && new_moved ) {
         moved = new_moved;
      }
   }
 
   /* Test if the screen is scrolling north/south. */
   new_pt = y1 - retroflat_viewport_world_y();
   if( new_pt > (retroflat_screen_h() >> 1) + range ) {
      new_moved = retroflat_viewport_move_y(
         gc_retroflat_offsets8_y[RETROFLAT_DIR8_SOUTH] * speed );
      if( !moved && new_moved ) {
         moved = new_moved;
      }
   } else if( new_pt < (retroflat_screen_h() >> 1) - range ) {
      new_moved = retroflat_viewport_move_y(
         gc_retroflat_offsets8_y[RETROFLAT_DIR8_NORTH] * speed );
      if( !moved && new_moved ) {
         moved = new_moved;
      }
   }
 
   return moved;
}
 
/* === */
 
MERROR_RETVAL retroflat_viewport_set_pos_size_generic(
   retroflat_pxxy_t x_px, retroflat_pxxy_t y_px,
   retroflat_pxxy_t w_px,  retroflat_pxxy_t h_px
) {
   MERROR_RETVAL retval = MERROR_OK;
   int x_tile = 0, y_tile = 0;
 
   if( w_px == retroflat_screen_w() && h_px == retroflat_screen_h() ) {
      debug_printf( 1, "fullscreen viewport; hardware scrolling enabled!" );
      g_retroflat_state->viewport.flags |= RETROFLAT_VIEWPORT_FLAG_FULLSCREEN;
   } else {
      g_retroflat_state->viewport.flags &= ~RETROFLAT_VIEWPORT_FLAG_FULLSCREEN;
   }
 
   /* We're not adding the extra two tiles on each dimension here since this
    * won't be used for indexing or allocation but rather pixel detection.
    */
   if(
      RETROFLAT_STATE_FLAG_HWSCROLLING ==
      (RETROFLAT_STATE_FLAG_HWSCROLLING & g_retroflat_state->retroflat_flags) &&
      RETROFLAT_VIEWPORT_FLAG_FULLSCREEN ==
      (RETROFLAT_VIEWPORT_FLAG_FULLSCREEN & g_retroflat_state->viewport.flags)
   ) {
      /* If fullscreen, allow arbitrary screen width/height since the hardware
       * scrolling should compensate for that.
       */
      g_retroflat_state->viewport.screen_w = w_px;
      g_retroflat_state->viewport.screen_h = h_px;
      g_retroflat_state->viewport.screen_w_remainder = 0;
      g_retroflat_state->viewport.screen_h_remainder = 0;
 
   } else {
      /* If not fullscreen, constrain to tile boundaries. */
      g_retroflat_state->viewport.screen_w =
         ((w_px) / RETROFLAT_TILE_W) * RETROFLAT_TILE_W;
      g_retroflat_state->viewport.screen_h =
         ((h_px) / RETROFLAT_TILE_H) * RETROFLAT_TILE_H;
      g_retroflat_state->viewport.screen_w_remainder =
         (x_px) + (w_px) - g_retroflat_state->viewport.screen_w;
      g_retroflat_state->viewport.screen_h_remainder =
         (y_px) + (h_px) - g_retroflat_state->viewport.screen_h;
   }
 
   g_retroflat_state->viewport.screen_x = x_px;
   g_retroflat_state->viewport.screen_y = y_px;
   g_retroflat_state->viewport.screen_tile_w = w_px / RETROFLAT_TILE_W;
   g_retroflat_state->viewport.screen_tile_h = h_px / RETROFLAT_TILE_H;
 
   /* Compensate for tiles that are cut off. */
   if( 0 != w_px % RETROFLAT_TILE_W ) {
      g_retroflat_state->viewport.screen_tile_w++;
   }
 
   if( 0 != h_px % RETROFLAT_TILE_H ) {
      g_retroflat_state->viewport.screen_tile_h++;
   }
 
   debug_printf( 1,
      "setting viewport screen size to %d x %d (%d x %d tiles)...",
      g_retroflat_state->viewport.screen_w,
      g_retroflat_state->viewport.screen_h,
      g_retroflat_state->viewport.screen_tile_w,
      g_retroflat_state->viewport.screen_tile_h );
 
#ifndef RETROFLAT_NO_VIEWPORT_REFRESH
   if( (MAUG_MHANDLE)NULL != g_retroflat_state->viewport.refresh_grid_h ) {
      maug_mfree( g_retroflat_state->viewport.refresh_grid_h );
   }
   debug_printf( 1, "allocating refresh grid (%d tiles, %d+2x%d+2...)",
      (g_retroflat_state->viewport.screen_tile_w + 2) *
      (g_retroflat_state->viewport.screen_tile_h + 2),
      g_retroflat_state->viewport.screen_tile_w,
      g_retroflat_state->viewport.screen_tile_h );
   maug_malloc_test(
      g_retroflat_state->viewport.refresh_grid_h,
      (g_retroflat_state->viewport.screen_tile_w + 2) *
      (g_retroflat_state->viewport.screen_tile_h + 2),
      sizeof( retroflat_tile_t ) );
 
   retroflat_viewport_lock_refresh();
   for(
      y_tile = 0 ; retroflat_viewport_screen_tile_h() + 2 > y_tile ; y_tile++
   ) {
      for(
         x_tile = 0 ; retroflat_viewport_screen_tile_w() + 2 > x_tile ; x_tile++
      ) {
         retroflat_viewport_grid_tile( x_tile, y_tile ) = -1;
      }
   }
   retroflat_viewport_unlock_refresh();
#endif /* !RETROFLAT_NO_VIEWPORT_REFRESH */
 
cleanup:
 
   return retval;
}
 
/* === */
 
#ifndef RETROFLAT_NO_VIEWPORT_REFRESH
 
uint8_t retroflat_viewport_tile_is_stale(
   int x_tile, int y_tile, retroflat_tile_t tile_id
) {
   int row_tiles = g_retroflat_state->viewport.screen_tile_w + 2;
 
   if(
      RETROFLAT_STATE_FLAG_HWSCROLLING ==
      (RETROFLAT_STATE_FLAG_HWSCROLLING & g_retroflat_state->retroflat_flags) &&
      RETROFLAT_VIEWPORT_FLAG_FULLSCREEN ==
      (RETROFLAT_VIEWPORT_FLAG_FULLSCREEN & g_retroflat_state->viewport.flags)
   ) {
      /* Turn negative index into positive. */
      x_tile++;
      y_tile++;
   }
 
#if RETROFLAT_VIEWPORT_GRID_TRACE_LVL > 0
   debug_printf( RETROFLAT_VIEWPORT_GRID_TRACE_LVL,
      "stale check x_tile: %d, y_tile: %d, idx: %d (%dx%d, %d total): %d vs %d",
      x_tile, y_tile,
      (y_tile * row_tiles) + x_tile,
      g_retroflat_state->viewport.screen_tile_w + 2,
      g_retroflat_state->viewport.screen_tile_h + 2,
      (g_retroflat_state->viewport.screen_tile_w + 2) *
      (g_retroflat_state->viewport.screen_tile_h + 2),
      tile_id, retroflat_viewport_grid_tile( x_tile, y_tile ) );
#endif /* RETROFLAT_VIEWPORT_GRID_TRACE_LVL */
 
   return tile_id != retroflat_viewport_grid_tile( x_tile, y_tile );
}
 
#endif /* !RETROFLAT_NO_VIEWPORT_REFRESH */
 
/* === */
 
MERROR_RETVAL retroflat_viewport_trim_px(
   struct RETROFLAT_BITMAP* bitmap,
   int16_t instance,
   retroflat_pxxy_t* s_x, retroflat_pxxy_t* s_y,
   retroflat_pxxy_t* d_x, retroflat_pxxy_t* d_y,
   retroflat_pxxy_t* w, retroflat_pxxy_t* h
) {
   retroflat_pxxy_t trim_bottom = *d_y + *h;
   retroflat_pxxy_t trim_right = *d_x + *w;
   retroflat_pxxy_t viewport_bottom = 0;
   retroflat_pxxy_t viewport_right = 0;
   retroflat_pxxy_t viewport_left = 0;
   retroflat_pxxy_t viewport_top = 0;
 
   if( 
      /* On the screen, constrain to the edges of the viewport. */
      retroflat_screen_buffer() == bitmap &&
      /* Probably blitting a window or other element that can go anywhere. */
      RETROFLAT_INSTANCE_NULL != instance &&
      /* The viewport is not fullscreen, so constrain to its tighter limits. */
      RETROFLAT_VIEWPORT_FLAG_FULLSCREEN !=
         (RETROFLAT_VIEWPORT_FLAG_FULLSCREEN &
            g_retroflat_state->viewport.flags)
   ) {
      viewport_left = retroflat_viewport_screen_get_x();
      viewport_top = retroflat_viewport_screen_get_y();
      viewport_bottom =
         (retroflat_viewport_screen_get_y() + retroflat_viewport_screen_h());
      viewport_right =
         (retroflat_viewport_screen_get_x() + retroflat_viewport_screen_w());
 
   } else {
      /* Constrain to the edges of the arbitrary bitmap. */
      viewport_bottom = retroflat_bitmap_h( bitmap );
      viewport_right = retroflat_bitmap_w( bitmap );
   }
 
   if( viewport_bottom < *d_y || trim_bottom < viewport_top ) {
#ifdef RETROFLAT_TRACE_CONSTRAIN
      error_printf( "attempted to blit bitmap way out of bounds at %d, %d!",
         *d_x, *d_y );
#endif /* RETROFLAT_TRACE_CONSTRAIN */
      return MERROR_GUI;
 
   } else if( viewport_bottom <= trim_bottom ) {
#ifdef RETROFLAT_TRACE_CONSTRAIN
      error_printf(
         "trimming " SIZE_T_FMT " pixels to get " SIZE_T_FMT " under "
            SIZE_T_FMT,
         trim_bottom - viewport_bottom, trim_bottom, viewport_bottom );
#endif /* RETROFLAT_TRACE_CONSTRAIN */
      *h -= (trim_bottom - viewport_bottom);
 
   } else if( viewport_top > *d_y ) {
#ifdef RETROFLAT_TRACE_CONSTRAIN
      error_printf(
         "trimming " SIZE_T_FMT " pixels to get " SIZE_T_FMT " under "
            SIZE_T_FMT,
         trim_bottom - viewport_bottom, trim_bottom, viewport_bottom );
#endif /* RETROFLAT_TRACE_CONSTRAIN */
      *h -= (viewport_top - *d_y);
      if( NULL != s_y ) {
         *s_y += (viewport_top - *d_y);
      }
      *d_y += (viewport_top - *d_y);
      assert( viewport_top == *d_y );
   }
 
   if( viewport_right < *d_x || trim_right < viewport_left ) {
#ifdef RETROFLAT_TRACE_CONSTRAIN
      error_printf( "attempted to blit bitmap way out of bounds at %d, %d!",
         *d_x, *d_y );
#endif /* RETROFLAT_TRACE_CONSTRAIN */
      return MERROR_GUI;
 
   } else if( viewport_right <= trim_right ) {
#ifdef RETROFLAT_TRACE_CONSTRAIN
      error_printf(
         "trimming " SIZE_T_FMT " pixels to get " SIZE_T_FMT " under "
            SIZE_T_FMT,
         trim_right - viewport_right, trim_right, viewport_right );
#endif /* RETROFLAT_TRACE_CONSTRAIN */
      *w -= (trim_right - viewport_right);
 
   } else if( viewport_left > *d_x ) {
#ifdef RETROFLAT_TRACE_CONSTRAIN
      error_printf(
         "trimming " SIZE_T_FMT " pixels to get " SIZE_T_FMT " under "
            SIZE_T_FMT,
         trim_bottom - viewport_bottom, trim_bottom, viewport_bottom );
#endif /* RETROFLAT_TRACE_CONSTRAIN */
      *w -= (viewport_left - *d_x);
      if( NULL != s_x ) {
         *s_x += (viewport_left - *d_x);
      }
      *d_x += (viewport_left - *d_x);
      assert( viewport_left == *d_x );
   }
 
   if( 0 == w && 0 == h ) {
      return MERROR_GUI;
   }
 
   return MERROR_OK;
}
 
/* === */
 
#ifndef RETROFLAT_NO_VIEWPORT_REFRESH
 
MERROR_RETVAL retroflat_viewport_clear_refresh( retroflat_pxxy_t y_max ) {
   MERROR_RETVAL retval = MERROR_OK;
   int x = 0, y = 0;
 
#if RETROTILE_TRACE_LVL > 0
   debug_printf( RETROTILE_TRACE_LVL,
      "clearing " SIZE_T_FMT " vertical viewport pixels (" SIZE_T_FMT
         " rows)...",
      y_max, y_max / RETROFLAT_TILE_H );
#endif /* RETROTILE_TRACE_LVL */
 
   retroflat_viewport_lock_refresh();
   for( y = 0 ; y_max > y ; y += RETROFLAT_TILE_H ) {
      for(
         x = 0 ; retroflat_viewport_screen_tile_w() > x ; x += RETROFLAT_TILE_W
      ) {
         retroflat_viewport_grid_tile( x, y ) = -1;
      }
   }
 
cleanup:
 
   retroflat_viewport_unlock_refresh();
 
   return retval;
}
 
#if 0
/* === */
 
MERROR_RETVAL retroflat_viewport_shift_x( int8_t shift ) {
   MERROR_RETVAL retval = MERROR_OK;
   int y_tile;
   /* Make some of these calculations appear less gnarly. */
 
   if( 0 == shift ) {
      error_printf( "null shift requested!" );
      retval = MERROR_GUI;
      goto cleanup;
   }
 
   /* Shift the adaptive refresh grid over accordingly, row by row. */
   retroflat_viewport_lock_refresh();
   for(
      y_tile = 0;
      (g_retroflat_state->viewport.screen_tile_h + 2) > y_tile;
      y_tile++
   ) {
      if( 0 < shift ) {
         /* Perform the (rightward) shift. */
         /*
         memmove(
            &(g_retroflat_state->viewport.refresh_grid[
               (y_tile * row_sz) + 1]),
            &(g_retroflat_state->viewport.refresh_grid[y_tile * row_sz]),
            row_sz - 1 );
         */
 
         /* Mark the oncoming tile as dirty. */
         retroflat_viewport_grid_tile( 0, y_tile ) = -1;
 
      } else {
         /* Perform the (leftward) shift. */
         /*
         memmove(
            &(g_retroflat_state->viewport.refresh_grid[y_tile * row_sz]),
            &(g_retroflat_state->viewport.refresh_grid[
               (y_tile * row_sz) + 1]),
            g_retroflat_state->viewport.screen_tile_w - 1 );
         */
 
         /* Mark the oncoming tile as dirty. */
         retroflat_viewport_grid_tile( 0, y_tile ) = -1;
      }
   }
   retroflat_viewport_unlock_refresh();
 
cleanup:
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL retroflat_viewport_shift_y( int8_t shift ) {
   MERROR_RETVAL retval = MERROR_OK;
   int y_tile;
   /* Make some of these calculations appear less gnarly. */
 
   /* Shift the adaptive refresh grid up/down accordingly, row by row. */
   retroflat_viewport_lock_refresh();
   if( 0 < shift ) {
      for(
         /* Start on the next-to-last row. */
         y_tile = g_retroflat_state->viewport.screen_tile_h;
         0 <= y_tile;
         /* Move upwards. */
         y_tile--
      ) {
         /*
         memmove(
            &(g_retroflat_state->viewport.refresh_grid[
               (y_tile + 1) * row_sz]),
            &(g_retroflat_state->viewport.refresh_grid[
               y_tile * row_sz]),
            row_sz );
         */
 
      }
 
      /* Mark the oncoming tiles as dirty. */
      memset(
         &retroflat_viewport_grid_tile( 0, y_tile ),
         -1,
         (g_retroflat_state->viewport.screen_tile_w + 2) *
            sizeof( retroflat_tile_t ) );
 
   } else {
      for(
         y_tile = 1;
         g_retroflat_state->viewport.screen_tile_h + 2 > y_tile;
         /* Move downwards. */
         y_tile++
      ) {
         /*
         memmove(
            &(g_retroflat_state->viewport.refresh_grid[
               (y_tile - 1) * row_sz]),
            &(g_retroflat_state->viewport.refresh_grid[
               y_tile * row_sz]),
            row_sz );
         */
 
      }
 
      /* Mark the oncoming tiles as dirty. */
      memset( &(g_retroflat_state->viewport.refresh_grid[0]), -1,
         (g_retroflat_state->viewport.screen_tile_w + 2) *
            sizeof( retroflat_tile_t ) );
   }
   retroflat_viewport_unlock_refresh();
 
cleanup:
 
   return retval;
}
#endif
 
#endif /* !RETROFLAT_NO_VIEWPORT_REFRESH */
 
#endif /* RETROVIW_C */