gfx_mode_select_filter(3)

💖 gfx_mode_select_filter 💖

okay bestie, so this one lives in the Allegro manual (section 3, the library functions girlies) and it's literally the most extra version of the graphics mode selection dialog. like, the one with the filter. the main character one. ✨

---

🎀 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. Even more extended version of the graphics mode selection dialog — and when I say more extended I mean she lets the programmer customize the actual contents of the dialog, AND lets the user pick the color depth on top of the resolution and the hardware driver. full package. 💅

Here's the tea on filter: it gets handed (card, w, h, color_depth) quadruplets, and it has to return 0 to let that specific quadruplet get added to the list of displayed modes. return anything else and she's filtered out, bye. 🦋

Same energy as gfx_mode_select though: the values sitting at the addresses you pass in get used as suggestions for the initial selections in the dialog. and if those values aren't found anywhere? it just defaults to the first entry in each list. no drama. 🌈

💡 pro tip bestie: if you want to be certain the initial selection for each list is the first entry, initialize the data at those addresses to 0 or -1. works every time, no cap.

And if the dialog gets OK'd, she stores the selections right back at the addresses you passed in. slay.

Example usage, copy it, it's cute:

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 ✨

• Returns zero if the user cancelled the dialog, or if an error happened. 😭 and in the error case, *card gets assigned the value GFX_NONE.
• Returns non-zero if the user actually made a selection OR if all the modes got filtered out. 🫶
• And in that "all the modes were filtered out" situation, *card also gets assigned the value GFX_NONE.

🚨 GIRLIE LISTEN. Because of all that, you should NOT initialize *card to the value of GFX_NONE — it could interfere with determining the proper return value. it's giving chaos. don't do it. periodt. 💀

---

👑 SEE ALSO 👑

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

---

okay that's the whole page, you ate it, you're welcome. 💖 this was Allegro version 4.4.3, and the page itself is dated with that same version. go forth and pick your graphics mode, bestie 🧚✨💜