gfx_mode_select_filter(3alleg4)

💖 gfx_mode_select_filter — the Allegro manual, but make it make sense

okay bestie, so this one is gfx_mode_select_filter(3alleg4), straight out of the Allegro manual, and it's literally the even more extended version of the graphics mode selection dialog. Allegro game programming library, iconic behavior, no cap. 🎀

✨ NAME ✨

gfx_mode_select_filter — Even more extended version of the graphics mode selection dialog. Allegro game programming library.

🌸 SYNOPSIS 🌸

#include <allegro.h>

int gfx_mode_select_filter(int *card, int *w, int *h, int *color_depth,
int (*filter)(int, int, int, int));

🦋 DESCRIPTION 🦋

so this is the even more extended version of the graphics mode selection dialog 💅 and it does the most in the best way: it lets the programmer customize what's inside the dialog, and lets the user pick the color depth as well as the resolution and the hardware driver. choices on choices on choices, we love to see it.

filter will be passed (card, w, h, color_depth) quadruplets, and it must return 0 to let that specified quadruplet get added to the list of displayed modes. return anything else and that mode is simply not invited to the party 🙈

same energy as gfx_mode_select, the values stored at the addresses you pass in get used as suggestions for the initial selections in the dialog — and if those values aren't found, it just defaults to the first entry in each list. so if you want to guarantee the initial selection for each list is the first entry, initialize the data at those addresses to 0 or -1. manifesting first-entry energy fr fr ✨

if the dialog gets OK'd, it stores the selections at the addresses you passed in. that's it, that's the whole vibe.

🍓 Example usage 🍓

ret = gfx_mode_select_filter(&card, &w, &h, &color_depth, user_filter);
if (ret) {/* User okayed dialog or user_filter removed all modes */
   if (card == GFX_NONE) {
      // No modes available
      *card = 0;/* Make sure not to leave *card == GFX_NONE */
      return -1;
   }
   /* Handle changing to new mode here... */

} else {/* User cancelled dialog or there was an error (unlikely) */
   if (card == GFX_NONE) {
      /* Error, probably out of memory */
      *card = 0;/* Make sure not to leave *card == GFX_NONE */
      return -2;
   }
   /* Carry on in current graphics mode if that is acceptable */
}

💀 RETURN VALUE 💀

okay pay attention because this part is giving plot twist:

• returns zero if the user cancelled the dialog or an error occurred. in the case of an error, *card is assigned the value GFX_NONE.
• returns non-zero if the user made a selection OR if all the modes were filtered out. and in the case that all of the modes were filtered out, *card is assigned the value GFX_NONE.

🚨 bestie LISTEN: this means you should NOT initialize *card to the value of GFX_NONE, because that could interfere with determining the proper return value. don't do it. i'm serious. it's giving self-sabotage. 😭

🔥 SEE ALSO 🔥

• gfx_mode_select(3alleg4)
• gfx_mode_select_ex(3alleg4)
• set_color_depth(3alleg4)
• set_gfx_mode(3alleg4)
• gui_fg_color(3alleg4)

and that's the whole page, bestie 🫶 this was Allegro version 4.4.3, page gfx_mode_select_filter(3alleg4) — go forth and pick your graphics mode, main character 💅✨🌈