[rcore] Clipboard Image Support

[evertonse]

[rcore] Clipboard Image

Overview

I've implemented a small start for Clipboard Image functionality for raylib. The implementation is only for desktop Windows OS and it's only GetClipboardImage. I want to implement SetClipboardImage, but I need to know a few things first regarding whether my approach is proper for the project.

2024-11-01.15-47-40.mp4

You'll see I created rcore_clipboard_win32 that implements this from scracth using winapi.
We can question "Why not use already implemented clipboard functions from platform abstractions such as GLFW, SDL, and RGFW and adpated to our needs?" Because they either did not implement it, or it is only available on the bleeding edge (SDL3).

• From what I've seen, SDL has clipboard image support but only since SDL 3.1.3 SDL_clipboard.h from SDL3. In that case, I check for the major and minor version and implement using SDL functions; otherwise, it just returns NULL (I could add a warning or implement using rcore_clipboard_win32). Also, SDL3 has a migration section, so I'm not even sure that the current raylib SDL platform is suited for SDL3. Just to double-check, there's no SDL_GetClipboardData in SDL2 SDL_clipboard.h from SDL2.

• RGFW only supports clipboard Unicode text from what I could see: RGFW.h - Line 643.

• GLFW is still in the process of implementing clipboard image functionality: GLFW Pull Request #2385.

How it is structured

In this PR, works like this: if we detect that the platform is either GLFW or RGFW and we're on Windows, then we include rcore_clipboard_win32.c. The file rcore_clipboard_win32.c went the route of defining windgi.h structs that are needed, taking care of any name collisions.

Takeaway

What I'm thinking is that when clipboard image manipulation becomes a stable feature for GLFW, we can easily add it to rcore_desktop_glfw. But for platforms that don't support it (such as SDL2, RGFW, and current GLFW) we could have "utils" platform functions such as GetClipboardImage (next would be SetClipboardImage) implemented seperatly such as in this PR.

Concerns

Another thing to add is that now it couples rcore and rtexture by the Image struct and the LoadImageFromMemory function. Furthermore, it is required to have SUPPORT_FILEFORMAT_BMP enabled.

Finally, the whole implementation is behind the flag SUPPORT_CLIPBOARD_IMAGE, which in this branch I've enabled by default in config.h.

I've added core_clipboard_image example to make it easy to check it out (it doesn't have to be permanent, also it hasn't updated its related files besides the examples Makefile)

This is kind of a draft. Sorry for the wall of text, I just tought it was important to share this to aid your decision and allow further development.

Update comment

[raysan5]

@evertonse This is an amazing addition! Thanks for working on it! About the best way to address this addition, it should be addressed by every supported rcore backend platform in a different way:

• RGFW: I think it could be directly added to RGFW.h library, probably its creator @ColleagueRiley can help on that.
• SDL: Functionality is already provided by the library so it can be directly supported by rcore_desktop_sdl backend, as already implemented.
• GLFW: This is the most tricky backend at the moment because despite there is an open PR on the base library it could take a lot of time to be merged. I'd prefer to avoid the current approach of implementing it in rcore_clipboard_win32.c, maybe it can be directly implemented in rcore_desktop_glfw.c? Another option could be rglfw.c module or move it to a separate external/win32_clipboard.c library.

Please, let me know your thoughts!

[ColleagueRiley]

@evertonse I'll look into this for RGFW ASAP 👍

[evertonse]

Update

I've worked on the desktop platforms much in the way it was suggested.

TLDR

Created an SDL3 layer to enable GetClipboardImage functionality , with the bonus that it works on Linux with SDL3. Additionally, for GLFW and RGFW, it was created a separate file, ./external/win32_clipboard.h to be used by both platforms.

SDL

To support clipboard images on the SDL platform, we need SDL3.
As I've suspected, the current implementation for rcore_platform_sdl is not compatible with SDL3.
To allow compilation with both versions (SDL2 and SDL3), it was created a compatibility layer following the SDL3 Migration Guide. Now it's possible to compile with both SDL2 or SDL3.

I have successfully ported the functionality as far as I could test, allowing GetClipboardImage function to work on Wayland Ubuntu, as shown below:

Untitled.video.-.Made.with.Clipchamp.1.mp4

Another benefit of adding SDL3 support is that some raylib functions that were previously unsupported on that platform are now available, such as GetWindowScaleDPI.

With SDL3, we now check for additional MIME types. I noticed that on Wayland Ubuntu, the clipboard saves images as PNG, so we now check for the following MIME types:

• image/bmp
• image/png
• image/jpg
• image/tiff

Compilation

Also I have modified the src/Makefile and examples/Makefile to enable compilation for SDL3.

After building and installing SDL3 on /usr/local, I was able to compile raylib and all examples with the following command (on Linux):

make PLATFORM=PLATFORM_DESKTOP_SDL  \
SDL_INCLUDE_PATH=/usr/local/include/SDL3/ \
SDL_LIBRARY_PATH=/usr/local/lib SDL_LIBRARIES=-lSDL3
export LD_LIBRARY_PATH=/usr/local/lib # libSDL3.so is located here

On MinGW, I used the following command to compile on Windows.
Consider SDL3 installed on ```~/.local/": we now need EXTRA_INCLUDE_PATHS because of the include style in SDL3.h (`<SDL3/file.h>`) as opposed to SDL2.h ("file.h"):

make PLATFORM=PLATFORM_DESKTOP_SDL  \
SDL_INCLUDE_PATH="$HOME/.local/include/SDL3/" EXTRA_INCLUDE_PATHS="-I$HOME/.local/include/"  \
SDL_LIBRARY_PATH=$HOME/.local/lib SDL_LIBRARIES=-lSDL3

We need to be aware that when compiling raylib with SDL3 on Windows, there is currently a chance of getting corrupted bitmaps from the clipboard in SDL3 version 3.1.6. I've opened a PR about this issue, and it has been added as a milestone for SDL 3.2.

It might be important to say that compiling SDL3 statically with raylib create's name colision now, because of these Matrix functions. It's still possible do compile statically if we use objcopy --redefine-sym on libSDL3.a

RGFW & GLFW

I followed your advice and created a header-only library in ./src/external/ for Windows only, which I used for the RGFW and GLFW platforms. As soon as both libraries implement this functionality we can roll back and implement GetClipboardImage in terms of those platforms.

Finally

If this approach is proper, I can continue working on the SetClipboardImage function. I consider this PR now ready for further review.

Quick example to test it

#include "raylib.h"

int main(int argc, char *argv[])
{
    InitWindow(800, 450, "[core] raylib clipboard image");
    SetTraceLogLevel(LOG_TRACE);
    SetTargetFPS(60);

    Image img = {0};
    Texture tex = {0};
    while(!WindowShouldClose())
    {
        if (IsKeyDown(KEY_LEFT_CONTROL) && IsKeyPressed(KEY_V))
        {
            img = GetClipboardImage();
            tex = LoadTextureFromImage(img);
            if(!IsTextureValid(tex))
            {
                TraceLog(LOG_WARNING, "Could not get clipboard image");
            }
        }

        BeginDrawing();
            ClearBackground(RAYWHITE);
            if (IsTextureValid(tex))
            {
                DrawTexture(tex, 0, 10 + 21, WHITE);
            }
            DrawText("Print Screen and Crtl+V", 10, 10, 21, BLACK);
        EndDrawing();
    }
}

[raysan5]

@evertonse Thank you very much for all the work put into this improvement!

It's a quite big PR containing many improvements; probably SDL3 support should be moved to a separate PR, but still, it looks clean and organized so it would be ok.

@ColleagueRiley could probably take a look to the win32_clipboard.h and rcore_desktop_rgfw.c implementations, some code could be moved RGFW.h base library.

If this approach is proper, I can continue working on the SetClipboardImage function. I consider this PR now ready for further review.

Sure, that would be fantastic.

Please, let me know if you plan any further work on this PR or I can merge it.

[evertonse]

Please, let me know if you plan any further work on this PR or I can merge it.

@raysan5 It's all good now, you can merge it.
I'll work on SetClipboardImage on a separate PR as it might take a bit of work.
Thank you for the support, sincerely :).

[raysan5]

@evertonse thanks for this great improvement!!!

[Not-Nik]

This breaks building on Windows when CUSTOMIZE_BUILD is specified.

[raysan5]

@Not-Nik I can't reproduce, what configuration do you mean?

[Not-Nik]

git clone raylib
cd raylib
mkdir build
cd build
cmake -DCUSTOMIZE_BUILD=ON ..
cmake --build .

System is

• Visual Studio 17 2022
• Windows SDK version 10.0.22000.0 to target Windows 10.0.19045
• MSVC 19.35.32216.1
• MSBuild version 17.5.1+f6fdcf537

and the error I get reads

fatal  error C1189: #error  "To enabled SUPPORT_CLIPBOARD_IMAGE, it also needs SUPPORT_FILEFORMAT_BMP, SUPPORT_MODULE_RTEXTURES and STBI_REQUIRED to be defined. It should have been defined earlier"

[evertonse]

and the error I get reads

We can turn that #error into #warning and make it compile (file src/rcore.c line 516).

Basically means one of these are not defined in the CUSTOMIZED build: SUPPORT_FILEFORMAT_BMP, STBI_REQUIRED SUPPORT_MODULE_RTEXTURES. Not defining these makes getting clipboard image less reliable, or may cause it to not work at all.

[Not-Nik]

The issue was more that I didn't enable SUPPORT_CLIPBOARD_IMAGE, so if it is somehow enabled by default, all its dependencies should also be enabled.

[evertonse]

so if it is somehow enabled by default, all its dependencies should also be enabled.

And they are, on config.h, but I think somehow -DCUSTOMIZE_BUILD doesn't pull config.h.
I guess I could enable its dependecies on rcore.c instead of config.h that might help.

For now I just made it into a warning in this PR