retrowin.h

Go to the documentation of this file.

 
#ifndef RETROW3D_H
#define RETROW3D_H

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

#define RETROWIN_FLAG_INIT_GUI          0x10
 
#define RETROWIN_FLAG_INIT_BMP          0x20
 
#define RETROWIN_FLAG_GUI_LOCKED        0x04
 
#define RETROWIN_FLAG_BORDER_NONE              0x00
#define RETROWIN_FLAG_BORDER_GRAY              0x01
#define RETROWIN_FLAG_BORDER_BLUE              0x02
 
#define retrowin_win_is_active( win ) \
   (RETROWIN_FLAG_INIT_BMP == (RETROWIN_FLAG_INIT_BMP & (win)->flags))
 
#define RETROWIN_FLAG_BORDER_MASK              0x03
 
#define retrowin_lock_gui( win ) \
   if( \
      RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & (win)->flags) && \
      RETROWIN_FLAG_GUI_LOCKED != (RETROWIN_FLAG_GUI_LOCKED & (win)->flags) \
   ) { \
      maug_mlock( (win)->gui_h, (win)->gui_p ); \
      maug_cleanup_if_null_lock( struct RETROGUI*, (win)->gui_p ); \
      (win)->flags |= RETROWIN_FLAG_GUI_LOCKED; \
   }
 
#define retrowin_unlock_gui( win ) \
   if( \
      RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & (win)->flags) && \
      RETROWIN_FLAG_GUI_LOCKED == (RETROWIN_FLAG_GUI_LOCKED & (win)->flags) \
   ) { \
      maug_munlock( (win)->gui_h, (win)->gui_p ); \
      (win)->flags &= ~RETROWIN_FLAG_GUI_LOCKED; \
   }
 
#define retrowin_gui_is_locked( win ) \
   (RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & (win)->flags) && \
   RETROWIN_FLAG_GUI_LOCKED == (RETROWIN_FLAG_GUI_LOCKED & (win)->flags))
 
struct RETROWIN {
   uint8_t flags;
   retrogui_idc_t idc;
   retroflat_pxxy_t x;
   retroflat_pxxy_t y;
   MAUG_MHANDLE gui_h;
   struct RETROGUI* gui_p;
#ifndef RETROWIN_NO_BITMAP
   retroflat_blit_t gui_bmp;
#endif /* !RETROWIN_NO_BITMAP */
};
 
MERROR_RETVAL retrowin_redraw_win_stack( struct MDATA_VECTOR* win_stack );

MERROR_RETVAL retrowin_refresh_win_stack( struct MDATA_VECTOR* win_stack );

retrogui_idc_t retrowin_poll_win_stack(
   struct MDATA_VECTOR* win_stack, retrogui_idc_t idc_active,
   RETROFLAT_IN_KEY* p_input, struct RETROFLAT_INPUT* input_evt );

ssize_t retrowin_get_win_stack_sel_idx(
   struct MDATA_VECTOR* win_stack,
   retrogui_idc_t idc_win, retrogui_idc_t idc_ctl );
 
void retrowin_free_win( struct RETROWIN* win );
 
MERROR_RETVAL retrowin_free_all_win( struct MDATA_VECTOR* win_stack );
 
ssize_t retrowin_get_by_idc(
   retrogui_idc_t idc, struct MDATA_VECTOR* win_stack );

ssize_t retrowin_push_win(
   struct RETROGUI* gui, struct MDATA_VECTOR* win_stack,
   retrogui_idc_t idc, const maug_path font_filename,
   retroflat_pxxy_t x, retroflat_pxxy_t y,
   retroflat_pxxy_t w, retroflat_pxxy_t h, uint8_t flags );

MERROR_RETVAL retrowin_destroy_win(
   struct MDATA_VECTOR* win_stack, retrogui_idc_t idc );
 
#ifdef RETROW3D_C
 
static MERROR_RETVAL _retrowin_draw_border( struct RETROWIN* win ) {
   MERROR_RETVAL retval = MERROR_OK;
   uint8_t autolock_gui = 0;
 
#if RETROWIN_TRACE_LVL > 0
   debug_printf( RETROWIN_TRACE_LVL, "drawing window border..." );
#endif /* RETROWIN_TRACE_LVL */
 
   if( !retrowin_gui_is_locked( win ) ) {
      retrowin_lock_gui( win );
      autolock_gui = 1;
   }
 
   switch( RETROWIN_FLAG_BORDER_MASK & win->flags ) {
   case RETROWIN_FLAG_BORDER_NONE:
      retroflat_2d_rect(
         win->gui_p->draw_bmp, RETROFLAT_COLOR_BLACK,
         win->gui_p->x,
         win->gui_p->y,
         win->gui_p->w,
         win->gui_p->h,
         RETROFLAT_DRAW_FLAG_FILL );
      break;
 
   case RETROWIN_FLAG_BORDER_GRAY:
      retroflat_2d_rect(
         win->gui_p->draw_bmp,
         2 < retroflat_screen_colors() ?
            RETROFLAT_COLOR_GRAY : RETROFLAT_COLOR_WHITE,
         win->gui_p->x,
         win->gui_p->y,
         win->gui_p->w,
         win->gui_p->h,
         RETROFLAT_DRAW_FLAG_FILL );
 
      /* Draw the border. */
      retroflat_2d_rect(
         win->gui_p->draw_bmp,
         2 < retroflat_screen_colors() ?
            RETROGUI_COLOR_BORDER : RETROFLAT_COLOR_BLACK,
         win->gui_p->x,
         win->gui_p->y,
         win->gui_p->w,
         win->gui_p->h,
         0 );
      if( 2 < retroflat_screen_colors() ) {
         /* Draw highlight lines only visible in >2-color mode. */
         retroflat_2d_line(
            win->gui_p->draw_bmp, RETROFLAT_COLOR_WHITE,
            win->gui_p->x + 1,
            win->gui_p->y + 1,
            win->gui_p->x + win->gui_p->w - 2,
            win->gui_p-> y + 1,
            0 );
         retroflat_2d_line(
            win->gui_p->draw_bmp, RETROFLAT_COLOR_WHITE,
            win->gui_p->x + 1,
            win->gui_p->y + 2,
            win->gui_p->x + 1,
            win->gui_p->y + win->gui_p->h - 3,
            0 );
      }
      break;
 
   case RETROWIN_FLAG_BORDER_BLUE:
      retroflat_2d_rect(
         win->gui_p->draw_bmp,
         2 < retroflat_screen_colors() ?
            RETROFLAT_COLOR_BLUE : RETROFLAT_COLOR_BLACK,
         win->gui_p->x,
         win->gui_p->y,
         win->gui_p->w,
         win->gui_p->h,
         RETROFLAT_DRAW_FLAG_FILL );
 
      /* Draw the border. */
      retroflat_2d_rect(
         win->gui_p->draw_bmp,
         2 < retroflat_screen_colors() ?
            RETROGUI_COLOR_BORDER : RETROFLAT_COLOR_BLACK,
         win->gui_p->x + 2,
         win->gui_p->y + 2,
         win->gui_p->w - 4,
         win->gui_p->h - 4,
         0 );
      retroflat_2d_rect(
         win->gui_p->draw_bmp, RETROFLAT_COLOR_WHITE,
         win->gui_p->x + 1,
         win->gui_p->y + 1,
         win->gui_p->w - 2,
         win->gui_p->h - 2,
         0 );
      retroflat_2d_rect(
         win->gui_p->draw_bmp,
         2 < retroflat_screen_colors() ?
            RETROGUI_COLOR_BORDER : RETROFLAT_COLOR_BLACK,
         win->gui_p->x,
         win->gui_p->y,
         win->gui_p->w,
         win->gui_p->h,
         0 );
      break;
   }
 
#if RETROWIN_TRACE_LVL > 0
   debug_printf( RETROWIN_TRACE_LVL, "drawing window border complete!" );
#endif /* RETROWIN_TRACE_LVL */
 
cleanup:
 
   if( autolock_gui ) {
      retrowin_unlock_gui( win );
   }
 
   return retval;
}
 
/* === */
 
static MERROR_RETVAL _retrowin_redraw_win( struct RETROWIN* win ) {
   MERROR_RETVAL retval = MERROR_OK;
   uint8_t autolock_gui = 0;
 
   if( !retrowin_gui_is_locked( win ) ) {
      retrowin_lock_gui( win );
      autolock_gui = 1;
   }
 
   /* Dirty detection is in retrogui_redraw_ctls(). */
 
#ifdef RETROWIN_NO_BITMAP
   win->gui_p->draw_bmp = NULL;
#else
   retroflat_2d_lock_bitmap( &(win->gui_bmp) );
   win->gui_p->draw_bmp = &(win->gui_bmp);
#endif /* RETROWIN_NO_BITMAP */
 
#if RETROWIN_TRACE_LVL > 0
   debug_printf( RETROWIN_TRACE_LVL,
      "redrawing window IDC " RETROGUI_IDC_FMT " at "
      PXXY_FMT ", " PXXY_FMT "...",
      win->idc, win->gui_p->x, win->gui_p->y );
#endif /* RETROWIN_TRACE_LVL */
 
#ifndef RETROWIN_NO_BITMAP
   /* This is a bit of a hack... Set X/Y to 0 so that we draw at the top
    * of the bitmap that will be used as a texture. Reset it below so input
    * detection works!
    */
   win->gui_p->x = 0;
   win->gui_p->y = 0;
#endif /* !RETROWIN_NO_BITMAP */
   retval = _retrowin_draw_border( win );
   if( MERROR_OK == retval ) {
      retval = retrogui_redraw_ctls( win->gui_p );
   }
#ifndef RETROWIN_NO_BITMAP
   win->gui_p->x = win->x;
   win->gui_p->y = win->y;
 
   retroflat_2d_release_bitmap( &(win->gui_bmp) );
#endif /* !RETROWIN_NO_BITMAP */
 
   maug_cleanup_if_not_ok();
 
#if RETROWIN_TRACE_LVL > 0
   debug_printf( RETROWIN_TRACE_LVL,
      "redraw of window IDC " RETROGUI_IDC_FMT " at "
      PXXY_FMT ", " PXXY_FMT " complete!",
      win->idc, win->gui_p->x, win->gui_p->y );
#endif /* RETROWIN_TRACE_LVL */
 
cleanup:
 
   if( autolock_gui ) {
      retrowin_unlock_gui( win );
   }
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL retrowin_redraw_win_stack( struct MDATA_VECTOR* win_stack ) {
   MERROR_RETVAL retval = MERROR_OK;
   size_t i = 0;
   struct RETROWIN* win = NULL;
   uint8_t autolock_stack = 0;
 
   if( 0 == mdata_vector_ct( win_stack ) ) {
      goto cleanup;
   }
 
   if( !mdata_vector_is_locked( win_stack ) ) {
      mdata_vector_lock( win_stack );
      autolock_stack = 1;
   }
 
   for( i = 0 ; mdata_vector_ct( win_stack ) > i ; i++ ) {
      win = mdata_vector_get( win_stack, i, struct RETROWIN );
      assert( NULL != win );
 
      if( !retrowin_win_is_active( win ) ) {
         continue;
      }
 
      retrowin_lock_gui( win );
 
#ifndef RETROWIN_NO_BITMAP
      if(
         RETROGUI_FLAGS_DIRTY == (RETROGUI_FLAGS_DIRTY & win->gui_p->flags)
      ) {
#endif /* !RETROWIN_NO_BITMAP */
#if RETROWIN_TRACE_LVL > 0
         debug_printf( RETROWIN_TRACE_LVL,
            "redrawing window idx " SIZE_T_FMT " with IDC " RETROGUI_IDC_FMT,
            i, win->idc );
#endif /* RETROWIN_TRACE_LVL */
 
         /* Redraw the window bitmap, including controls. */
         retval = _retrowin_redraw_win( win );
         maug_cleanup_if_not_ok();
#ifndef RETROWIN_NO_BITMAP
      }
#endif /* !RETROWIN_NO_BITMAP */
 
#ifndef RETROWIN_NO_BITMAP
      /* Always blit the finished window to the screen, to compensate for e.g.
       * the implicit screen-clearing of the engine loop.
       */
      retval = retroflat_2d_blit_win(
         &(win->gui_bmp), win->gui_p->x, win->gui_p->y );
#endif /* !RETROWIN_NO_BITMAP */
 
      retrowin_unlock_gui( win );
 
#if RETROWIN_TRACE_LVL > 0
      debug_printf( RETROWIN_TRACE_LVL,
         "redraw of window idx " SIZE_T_FMT " with IDC " RETROGUI_IDC_FMT
            " complete!",
         i, win->idc );
#endif /* RETROWIN_TRACE_LVL */
   }
 
#if RETROWIN_TRACE_LVL > 0
      debug_printf( RETROWIN_TRACE_LVL, "redraw of all windows complete!" );
#endif /* RETROWIN_TRACE_LVL */
 
cleanup:
 
   if( autolock_stack ) {
      mdata_vector_unlock( win_stack );
   }
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL retrowin_refresh_win_stack( struct MDATA_VECTOR* win_stack ) {
   MERROR_RETVAL retval = MERROR_OK;
   size_t i = 0;
   struct RETROWIN* win = NULL;
   uint8_t autolock_stack = 0;
 
   if( 0 == mdata_vector_ct( win_stack ) ) {
      goto cleanup;
   }
 
   if( !mdata_vector_is_locked( win_stack ) ) {
      mdata_vector_lock( win_stack );
      autolock_stack = 1;
   }
 
   for( i = 0 ; mdata_vector_ct( win_stack ) > i ; i++ ) {
      win = mdata_vector_get( win_stack, i, struct RETROWIN );
      assert( NULL != win );
 
      if( !retrowin_win_is_active( win ) ) {
         continue;
      }
 
      retrowin_lock_gui( win );
 
#if RETROWIN_TRACE_LVL > 0
      debug_printf( RETROWIN_TRACE_LVL,
         "refreshing window idx " SIZE_T_FMT " with IDC " RETROGUI_IDC_FMT,
         i, win->idc );
#endif /* RETROWIN_TRACE_LVL */
 
      win->gui_p->flags |= RETROGUI_FLAGS_DIRTY;
 
      retrowin_unlock_gui( win );
   }
 
cleanup:
 
   if( autolock_stack ) {
      mdata_vector_unlock( win_stack );
   }
 
   return retval;
}
 
/* === */
 
retrogui_idc_t retrowin_poll_win_stack(
   struct MDATA_VECTOR* win_stack, retrogui_idc_t idc_active,
   RETROFLAT_IN_KEY* p_input, struct RETROFLAT_INPUT* input_evt
) {
   retrogui_idc_t idc_out = RETROGUI_IDC_NONE;
   MERROR_RETVAL retval = MERROR_OK;
   struct RETROWIN* win = NULL;
   int autolock = 0;
   ssize_t win_idx = -1;
 
   if( !mdata_vector_is_locked( win_stack ) ) {
      mdata_vector_lock( win_stack );
      autolock = 1;
   }
 
   win_idx = retrowin_get_by_idc( idc_active, win_stack );
   if( 0 > win_idx ) {
      /* No window found! */
      error_printf( "polling missing window!" );
      retval = MERROR_GUI;
      goto cleanup;
   }
 
   win = mdata_vector_get( win_stack, win_idx, struct RETROWIN );
   assert( NULL != win );
   assert( idc_active == win->idc );
   if( !retrowin_win_is_active( win ) ) {
      /* Window not initialized! */
      error_printf( "polling uninitialized window!" );
      retval = MERROR_GUI;
      goto cleanup;
   }
 
   retrowin_lock_gui( win );
   if( 0 != *p_input ) {
#if RETROWIN_TRACE_LVL > 0
      debug_printf( RETROWIN_TRACE_LVL,
         "polling window idx " SIZE_T_FMT " with IDC " RETROGUI_IDC_FMT,
         win_idx, win->idc );
#endif /* RETROWIN_TRACE_LVL */
   }
   idc_out = retrogui_poll_ctls( win->gui_p, p_input, input_evt );
   retrowin_unlock_gui( win );
 
cleanup:
 
   if( MERROR_OK != retval ) {
      error_printf( "error polling windows!" );
      idc_out = merror_retval_to_sz( retval );
   }
 
   if( autolock ) {
      mdata_vector_unlock( win_stack );
   }
 
   return idc_out;
}
 
/* === */
 
ssize_t retrowin_get_win_stack_sel_idx(
   struct MDATA_VECTOR* win_stack,
   retrogui_idc_t idc_win, retrogui_idc_t idc_ctl
) {
   ssize_t idx_out = -1;
   MERROR_RETVAL retval = MERROR_OK;
   struct RETROWIN* win = NULL;
   int autolock = 0;
   ssize_t win_idx = -1;
 
   if( !mdata_vector_is_locked( win_stack ) ) {
      mdata_vector_lock( win_stack );
      autolock = 1;
   }
 
   win_idx = retrowin_get_by_idc( idc_win, win_stack );
   if( 0 > win_idx ) {
      /* No window found! */
      error_printf( "polling invalid window!" );
      goto cleanup;
   }
 
   win = mdata_vector_get( win_stack, win_idx, struct RETROWIN );
   assert( NULL != win );
   assert( idc_win == win->idc );
   if( !retrowin_win_is_active( win ) ) {
      /* Window not active! */
      error_printf( "polling inactive window!" );
      goto cleanup;
   }
 
   retrowin_lock_gui( win );
   idx_out = retrogui_get_ctl_sel_idx( win->gui_p, idc_ctl );
   retrowin_unlock_gui( win );
 
cleanup:
 
   if( MERROR_OK != retval ) {
      error_printf( "error getting window control selection index!" );
      idx_out = merror_retval_to_sz( retval );
   }
 
   if( autolock ) {
      mdata_vector_unlock( win_stack );
   }
 
   return idx_out;
}
 
/* === */
 
void retrowin_free_win( struct RETROWIN* win ) {
   MERROR_RETVAL retval = MERROR_OK;
 
   if( RETROWIN_FLAG_INIT_BMP == (RETROWIN_FLAG_INIT_BMP & win->flags) ) {
#ifndef RETROWIN_NO_BITMAP
      retroflat_2d_destroy_bitmap( &(win->gui_bmp) );
#endif /* !RETROWIN_NO_BITMAP */
      retrowin_lock_gui( win );
      win->gui_p->draw_bmp = NULL;
      retrowin_unlock_gui( win );
   }
 
   if( RETROWIN_FLAG_INIT_GUI == (RETROWIN_FLAG_INIT_GUI & win->flags) ) {
      /* This GUI was created by a NULL to push_win(). */
      retrowin_lock_gui( win )
      retrogui_destroy( win->gui_p );
      retrowin_unlock_gui( win )
      maug_mfree( win->gui_h );
   }
 
cleanup:
 
   if( MERROR_OK != retval ) {
      error_printf( "error while locking self-managed GUI! not freed!" );
   }
 
   maug_mzero( win, sizeof( struct RETROWIN ) );
}
 
/* === */
 
MERROR_RETVAL retrowin_free_all_win( struct MDATA_VECTOR* win_stack ) {
   MERROR_RETVAL retval = MERROR_OK;
   struct RETROWIN* win = NULL;
 
   if( 0 < mdata_vector_ct( win_stack ) ) {
      mdata_vector_lock( win_stack );
      while( 0 < mdata_vector_ct( win_stack ) ) {
         win = mdata_vector_get( win_stack, 0, struct RETROWIN );
         assert( NULL != win );
         retrowin_free_win( win );
         mdata_vector_unlock( win_stack );
         mdata_vector_remove( win_stack, 0 );
         mdata_vector_lock( win_stack );
      }
      mdata_vector_unlock( win_stack );
   }
   mdata_vector_free( win_stack );
 
cleanup:
 
   return retval;
}
 
/* === */
 
ssize_t retrowin_get_by_idc(
   retrogui_idc_t idc, struct MDATA_VECTOR* win_stack
) {
   ssize_t idx_out = -1;
   int autolock = 0;
   size_t i = 0;
   struct RETROWIN const* win = NULL;
   MERROR_RETVAL retval = MERROR_OK;
 
   if( 0 == mdata_vector_ct( win_stack ) ) {
      goto cleanup;
   }
 
   if( !mdata_vector_is_locked( win_stack ) ) {
      mdata_vector_lock( win_stack );
      autolock = 1;
   }
 
   for( i = 0 ; mdata_vector_ct( win_stack ) > i ; i++ ) {
      win = mdata_vector_get( win_stack, i, struct RETROWIN );
      if( idc == win->idc ) {
         idx_out = i;
         goto cleanup;
      }
   }
 
cleanup:
 
   if( autolock ) {
      mdata_vector_unlock( win_stack );
   }
 
   if( MERROR_OK != retval ) {
      idx_out = merror_retval_to_sz( retval );
   }
 
   return idx_out;
}
 
/* === */
 
ssize_t retrowin_push_win(
   struct RETROGUI* gui, struct MDATA_VECTOR* win_stack,
   retrogui_idc_t idc, const maug_path font_filename,
   retroflat_pxxy_t x, retroflat_pxxy_t y,
   retroflat_pxxy_t w, retroflat_pxxy_t h, uint8_t flags
) {
   MERROR_RETVAL retval = MERROR_OK;
   struct RETROWIN win;
   ssize_t idx_out = -1;
 
   if( RETROGUI_IDC_NONE >= idc ) {
      error_printf( "invalid IDC: %d", idc );
      retval = MERROR_GUI;
      goto cleanup;
   }
 
   if(
      0 > x || 0 > y ||
      retroflat_screen_w() < x + w || retroflat_screen_h() < y + h
   ) {
      error_printf( "attempting to create window with IDC " RETROGUI_IDC_FMT
         " offscreen at %d, %d (%d x %d)", idc, x, y, w, h );
      retval = MERROR_GUI;
      goto cleanup;
   }
 
   idx_out = retrowin_get_by_idc( idc, win_stack );
   if( 0 <= idx_out ) {
      error_printf(
         "window with IDC " RETROGUI_IDC_FMT " already exists!", idc );
      retval = MERROR_GUI;
      goto cleanup;
   }
 
   maug_mzero( &win, sizeof( struct RETROWIN ) );
 
   win.flags = 0;
 
   if( NULL != gui ) {
      win.gui_p = gui;
   } else {
#if RETROWIN_TRACE_LVL > 0
      debug_printf( RETROWIN_TRACE_LVL,
         "creating self-owned GUI for window with IDC " RETROGUI_IDC_FMT ": "
         PXXY_FMT "x" PXXY_FMT " @ " PXXY_FMT ", " PXXY_FMT,
         idc, w, h, x, y );
#endif /* RETROWIN_TRACE_LVL */
 
      win.gui_p = NULL;
      maug_malloc_test( win.gui_h, 1, sizeof( struct RETROGUI ) );
 
      win.flags |= RETROWIN_FLAG_INIT_GUI;
 
      debug_printf( RETROWIN_TRACE_LVL, "x0" );
 
      /* Prepare gui_p for use as if it had just been assigned. */
      retrowin_lock_gui( &win );
 
      debug_printf( RETROWIN_TRACE_LVL, "x1" );
 
      retval = retrogui_init( win.gui_p );
      maug_cleanup_if_not_ok();
 
      debug_printf( RETROWIN_TRACE_LVL, "x2" );
 
      retval = retrogui_set_font( win.gui_p, font_filename );
      maug_cleanup_if_not_ok();
 
      debug_printf( RETROWIN_TRACE_LVL, "x3" );
   }
 
#ifndef RETROWIN_NO_BITMAP
   retval = retroflat_2d_create_bitmap(
      w, h, &(win.gui_bmp),
      RETROFLAT_BITMAP_FLAG_OPAQUE );
   maug_cleanup_if_not_ok_msg( "error creating window bitmap!" );
#endif /* !RETROWIN_NO_BITMAP */
 
   win.flags |= RETROWIN_FLAG_INIT_BMP;
 
   win.gui_p->w = w;
   win.gui_p->h = h;
   /* These might seem redundant, but check out retrowin_redraw_win()
    * to see how they're used.
    */
   win.x = x;
   win.y = y;
   win.gui_p->x = x;
   win.gui_p->y = y;
   win.idc = idc;
   win.flags |= flags;
 
#if RETROWIN_TRACE_LVL > 0
   debug_printf( RETROWIN_TRACE_LVL,
      "pushing window with IDC " RETROGUI_IDC_FMT ": "
         PXXY_FMT "x" PXXY_FMT " @ " PXXY_FMT ", " PXXY_FMT,
      win.idc, win.gui_p->w, win.gui_p->h, win.gui_p->x, win.gui_p->y );
#endif /* RETROWIN_TRACE_LVL */
 
   retrowin_unlock_gui( &win );
 
   idx_out = mdata_vector_append( win_stack, &win, sizeof( struct RETROWIN ) );
   if( 0 > idx_out ) {
      goto cleanup;
   }
 
   if( w != h ) {
      /* TODO: Update to detect proportional windows. */
      error_printf(
         "non-square window created; some systems may have trouble!" );
   }
 
   retrowin_refresh_win_stack( win_stack );
 
cleanup:
 
   /* Unlock if unlock above was skipped due to error. */
   retrowin_unlock_gui( &win );
 
   return idx_out;
}
 
/* === */
 
MERROR_RETVAL retrowin_destroy_win(
   struct MDATA_VECTOR* win_stack, retrogui_idc_t idc
) {
   size_t i = 0;
   MERROR_RETVAL retval = MERROR_OK;
   struct RETROWIN* win = NULL;
   ssize_t i_free = -1;
   int autolock = 0;
 
#if RETROWIN_TRACE_LVL > 0
   debug_printf( RETROWIN_TRACE_LVL,
      "attempting to destroy window with IDC " RETROGUI_IDC_FMT, idc );
#endif /* RETROWIN_TRACE_LVL */
 
   if( !mdata_vector_is_locked( win_stack ) ) {
      mdata_vector_lock( win_stack );
      autolock = 1;
   }
 
   for( i = 0 ; mdata_vector_ct( win_stack ) > i ; i++ ) {
      win = mdata_vector_get( win_stack, i, struct RETROWIN );
      assert( NULL != win );
      if( idc != win->idc ) {
         continue;
      }
 
      if( !retrowin_win_is_active( win ) ) {
#if RETROWIN_TRACE_LVL > 0
         debug_printf( RETROWIN_TRACE_LVL,
            "window with IDC " RETROGUI_IDC_FMT
               " found, but not active! (flags: 0x%02x)",
            idc, win->flags );
#endif /* RETROWIN_TRACE_LVL */
         continue;
      }
 
#if RETROWIN_TRACE_LVL > 0
      debug_printf( RETROWIN_TRACE_LVL,
         "freeing window with IDC " RETROGUI_IDC_FMT, win->idc );
#endif /* RETROWIN_TRACE_LVL */
 
      retrowin_free_win( win );
 
      i_free = i;
 
      break;
   }
 
   /* Remove the window from the vector if asked to. */
   if( 0 <= i_free ) {
      if( autolock ) {
         mdata_vector_unlock( win_stack );
      }
      mdata_vector_remove( win_stack, i_free );
      if( autolock ) {
         mdata_vector_lock( win_stack );
      }
   }
 
cleanup:
 
   if( autolock ) {
      mdata_vector_unlock( win_stack );
   }
 
   return retval;
}
 
#endif /* RETROW3D_C */
 /* maug_retrowin */
 /* maug_retroflt */
 
#endif /* !RETROW3D_H */