Yalantis/uCrop · error · CImgDisplayException

screenshot(): Screenshot feature is not supported when using

Error message

screenshot(): Screenshot feature is not supported when using SDL3-based display.

What it means

The SDL3 build of CImgDisplay implements screenshot() as a stub that always throws CImgDisplayException: capturing screen content is not implemented for the SDL3 display backend. Unlike the X11/GDI/Win32 backends, there is no native screen-grab path wired up, so the static screenshot() overloads are unconditionally unsupported here.

Source

Thrown at ucrop/src/main/jni/CImg.h:12635

            const unsigned char
              R = (unsigned char)((*(data1++) - _min)*mm),
              G = (unsigned char)((*(data2++) - _min)*mm),
              B = (unsigned char)((*(data3++) - _min)*mm);
            *(ptrd++) = (unsigned int)((R<<24) | (G<<16) | (B<<8) | 255);
          }
        }
        }
      }
      if (ndata!=_data) { _render_resize(ndata,img._width,img._height,_data,_width,_height); delete[] ndata; }
      SDL3_attr.unlock();

//      process_events(false);
      return *this;
    }

    template<typename T>
    static void screenshot(const int, const int, const int, const int, CImg<T>&) {
      throw CImgDisplayException("screenshot(): Screenshot feature is not supported when using SDL3-based display.");
    }

    template<typename T>
    const CImgDisplay& snapshot(CImg<T>& img) const {
      if (is_empty()) { img.assign(); return *this; }
      const unsigned int *ptrs = _data;
      img.assign(_width,_height,1,3);
      T
        *data1 = img.data(0,0,0,0),
        *data2 = img.data(0,0,0,1),
        *data3 = img.data(0,0,0,2);
      for (cimg_ulong xy = (cimg_ulong)img._width*img._height; xy>0; --xy) {
        const unsigned int val = *(ptrs++);
        *(data1++) = (T)(unsigned char)(val>>24);
        *(data2++) = (T)(unsigned char)((val>>16)&0xFF);
        *(data3++) = (T)(unsigned char)((val>>8)&0xFF);
      }
      return *this;

View on GitHub (pinned to f788b534b4)

Solutions

1. Build with a supported display backend (cimg_display=1 X11, =2 Win32/GDI) if screenshot() is required.
2. Replace screenshot() with an SDL3-native or OS-level capture (e.g. SDL_RenderReadPixels on your own renderer, or a platform screen-capture API).
3. Wrap the call in a capability check for your backend and degrade gracefully.

Example fix

// before
CImg<unsigned char> cap;
CImgDisplay::screenshot(0,0,w,h,cap); // throws under SDL3
// after
#if cimg_display != 3
CImg<unsigned char> cap;
CImgDisplay::screenshot(0,0,w,h,cap);
#endif

#if cimg_display == 3
#error screenshot() unsupported with SDL3 backend
#endif

constexpr bool screenshot_supported = (cimg_display != 3);

try { CImgDisplay::screenshot(0,0,w,h,cap); }
catch (cimg_library::CImgDisplayException &e) { /* use SDL/OS capture instead */ }

When it happens

Trigger: Calling any CImgDisplay::screenshot(x,y,w,h,img) overload in a build compiled with cimg_display=3 (SDL3).

Common situations: Porting code that used screenshot() with the X11 or Win32 backend to an SDL3 build; assuming feature parity across CImg display backends; build scripts switched the CImg display type to SDL3.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• cimg::SDL3_attr(): %s
• load_jxl(): Does not support animated JPEG XL '%s'.
• cimg::mod(): Specified modulo value is 0.
• cimg::fopen(): Specified file path is (null).
• cimg::fopen(): File '%s', specified mode is (null).

AI-assisted analysis of Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/a12a20e953e113ed. Report an issue: GitHub.