# Binary Resource Tutorial

**URL:** <https://forum.juce.com/t/binary-resource-tutorial/45047>\
**Category:** Getting Started\
**Created:** [March 16, 2021, 6:51pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047 "2021-03-16T18:51:15Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![lucianthorr](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/lucianthorr/32/6706_2.png) [@lucianthorr](https://forum.juce.com/u/lucianthorr)\
**Post date:** [March 16, 2021, 6:51pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/1 "2021-03-16T18:51:15Z")

</div>

Hello! Are there any resources for learning how to access and use assets that are bundled together as binary data (specifically in visual studio if that matters).  
I see quite a few references to using BinaryData but I haven’t run into any clear examples and I don’t see it mentioned in the JUCE: Class Index so maybe it’s depreciated?

I’m sure I’m overlooking them or I’m using the wrong words in my google searches  
Thanks

---

<div class="post-metadata">

**Author:** ![TeotiGraphix](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/teotigraphix/32/2016_2.png) [@TeotiGraphix](https://forum.juce.com/u/TeotiGraphix)\
**Post date:** [March 16, 2021, 7:35pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/2 "2021-03-16T19:35:59Z")

</div>

> [@Help adding images/binary data](https://forum.juce.com/t/help-adding-images-binary-data/24012):
>
> Hi, I want to add resources to Juce. I added a new group called Resources. Then add ‘existing file’ and select my .png file. It then adds it with ‘Binary Resource’ ticked. When I save and load it into my IDE (VS) it appears as a png file rather than a text file. Am I doing anything wrong? I thought we’re supposed to make separate files out of our resources.

> [@Adding an image to your JUCE application \[SOLVED\]](https://forum.juce.com/t/adding-an-image-to-your-juce-application-solved/33923):
>
> I wanted to incorporate an image into my component. (Eventually I want to play an animated GIF, but baby steps first!). So I peruse the documentation, and this is the best I came up with: first create a default constructed Image gifImage; in the private: section as this will store an invalid Image for us on the stack, ready for us when we load it up with something: Then we need a File object to store the path to the file. Initially I tried File file{“test.gif”} And even though the documentatio…

> [@How to add a background image](https://forum.juce.com/t/how-to-add-a-background-image/21454):
>
> I’m in the process of learning JUCE (and C++) and by now I’ve done most of the tutorials for Mac OS X with XCode 8.2.1. I know how to add buttons, sliders and how to handle MIDI events (I think ;-)). Now I want to build a standalone app. This app is a (kind of) remote control for my synthesizer (Kurzweil K2500R). Basically rather simple, but at the moment I’m stuck. I want to add an image of the frontpanel of the K2500R as a background image to the app. I managed to use the BinaryBuilder tool to…

A couple threads.

These resources are added in the Projucer which creates the BinaryData h/cpp to access in code.

[https://juce.com/discover/stories/projucer-manual](https://juce.com/discover/stories/projucer-manual)

See; **5.2 File Explorer Folder Settings**

`Binary Resource	- The file is added as a binary resource in your executable. Counts towards your platform-specific binary app size limits.`

---

<div class="post-metadata">

**Author:** ![lucianthorr](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/lucianthorr/32/6706_2.png) [@lucianthorr](https://forum.juce.com/u/lucianthorr)\
**Post date:** [March 17, 2021, 12:51pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/3 "2021-03-17T12:51:28Z")

</div>

Thanks @TeotiGraphix

I believe I was missing some fundamental aspects of BinaryData that were just assumed knowledge. After tracking down some example usage, I have a better understanding of BinaryData and how to use it. I’ll add these notes here for any future-self’s that aren’t sure where to start.

First off, BinaryData is code generated by the Projucer based on files that the user has added and checked the “Binary Resources” option in the Projucer’s File Explorer. Therefore, BinaryData is NOT a JUCE module and that explains why there is no API documentation for it in the JUCE Class Index.

It does have some standard variables and functions available though

```
// Number of elements in the namedResourceList and originalFileNames arrays.
const int namedResourceListSize = 33; // value depends on # of files you've added

// Points to the start of a list of resource names.
extern const char* namedResourceList[];

// Points to the start of a list of resource filenames.
extern const char* originalFilenames[];

// If you provide the name of one of the binary resource variables above, this function will
// return the corresponding data and its size (or a null pointer if the name isn't found).
const char* getNamedResource (const char* resourceNameUTF8, int& dataSizeInBytes);

// If you provide the name of one of the binary resource variables above, this function will
// return the corresponding original, non-mangled filename (or a null pointer if the name isn't found).
const char* getNamedResourceOriginalFilename (const char* resourceNameUTF8);

```

You don’t have to explicitly import BinaryData. just access the variables and functions directly.

ie,

```
char* firstItem = BinaryData::namedResourceList[0];
// or 
char* firstItem = BinaryData::example_test_txt
```

---

<div class="post-metadata">

**Author:** ![jacopoeftilo](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/jacopoeftilo/32/20936_2.png) [@jacopoeftilo](https://forum.juce.com/u/jacopoeftilo)\
**Post date:** [June 1, 2022, 8:19pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/4 "2022-06-01T20:19:42Z")

</div>

Sorry to bump this old post. I generated my `BinaryData` using the `BindaryBuilder` and the created `BinaryData.h` file does not contain the definitions of `namedResourceListSize`, `namedResourceList`, `originalFilenames`, `getNamedResource` and `getNamedReourceOriginalFilename` but it only contains the definitions of the assets that I added and their size. Why are those definitions missing?

---

<div class="post-metadata">

**Author:** ![cpr2323](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/cpr2323/32/18682_2.png) [@cpr2323](https://forum.juce.com/u/cpr2323)\
**Post date:** [June 1, 2022, 10:17pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/5 "2022-06-01T22:17:00Z")

</div>

Taking a quick look at the code, those don’t get added by BinaryBuilder, they are added by Projucer when it creates the BinaryData files. There is a class, called **ResourceFile** (in `extras\Build\juce_build_tools\utils\juce_BinaryResourceFile.cpp`) which does all the heavy lifting. I don’t know what is best practice to generate that code if you aren’t using Projucer, so I can’t offer more than the results of my detective work.

---

<div class="post-metadata">

**Author:** ![jacopoeftilo](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/jacopoeftilo/32/20936_2.png) [@jacopoeftilo](https://forum.juce.com/u/jacopoeftilo)\
**Post date:** [June 2, 2022, 6:43pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/6 "2022-06-02T18:43:51Z")

</div>

That’s what I noticed too when looking at the BinaryBuilder source code. I’m still using the Projucer but I’d like to switch to CMake sometime, so it would be nice if the BinaryData generated with the 2 methods would be identical, I wonder why that’s not the case.

---

<div class="post-metadata">

**Author:** ![cpr2323](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/cpr2323/32/18682_2.png) [@cpr2323](https://forum.juce.com/u/cpr2323)\
**Post date:** [June 2, 2022, 7:02pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/7 "2022-06-02T19:02:01Z")

</div>

I wondered that exact thing when looking into this. Best of luck. I want to move to cmake too, so I hope there is a solution. If nothing else, since the source code is available, one could write their own tool. 🤓

---

<div class="post-metadata">

**Author:** ![jacopoeftilo](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/jacopoeftilo/32/20936_2.png) [@jacopoeftilo](https://forum.juce.com/u/jacopoeftilo)\
**Post date:** [June 2, 2022, 7:40pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/8 "2022-06-02T19:40:34Z")

</div>

I haven’t tried it yet, but there is a `juce_add_binary_data` module for CMake that might do the trick. Otherwise the functionalities should be in `juce_BinaryResourceFile.h/cpp` and can just be replicated.

---

<div class="post-metadata">

**Author:** ![PluginPenguin](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/pluginpenguin/32/10203_2.png) [@PluginPenguin](https://forum.juce.com/u/PluginPenguin)\
**Post date:** [June 3, 2022, 6:32am UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/9 "2022-06-03T06:32:37Z")

</div>

Just out of interest, what real-world uses cases do you have for those name lists and functions taking the file name? All the time working with binary data I always accessed the assets directly like e.g.

```auto
auto fooImage = juce::ImageFileFormat::loadFrom (BinaryData::foo_png, BinaryData::foo_pngSize);
auto barImage = juce::ImageFileFormat::loadFrom (BinaryData::bar_png, BinaryData::bar_pngSize);

```

---

<div class="post-metadata">

**Author:** ![jacopoeftilo](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/jacopoeftilo/32/20936_2.png) [@jacopoeftilo](https://forum.juce.com/u/jacopoeftilo)\
**Post date:** [June 3, 2022, 8:58am UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/10 "2022-06-03T08:58:53Z")

</div>

I was figuring out how to write a cross platform presets. While checking out some open source projects I noticed those lists and functions used to loop through the presets I guess stored in the BinaryData.

---

<div class="post-metadata">

**Author:** ![PluginPenguin](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/pluginpenguin/32/10203_2.png) [@PluginPenguin](https://forum.juce.com/u/PluginPenguin)\
**Post date:** [June 3, 2022, 3:13pm UTC](https://forum.juce.com/t/binary-resource-tutorial/45047/11 "2022-06-03T15:13:04Z")

</div>

Ah I see. We usually take a hand written `std::map` for stuff like that.

[Example code modern C++ 20 features](https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1DIApACYAQuYukl9ZATwDKjdAGFUtAK4sGIAMykrgAyeAyYAHI%2BAEaYxAEAnKQADqgKhE4MHt6%2BeqnpjgKh4VEssfFcABy2mPaFDEIETMQE2T5%2BgXaYDpmNzQTFkTFxibZNLW25XGP9g6XlEpUAlLaoXsTI7Bzm/mHI3lgA1Cb%2BbixMySfYJhoAgjt7B5jHpwoExGHAAPoAbniYAHcrjd7mZdgx9l4jic3ApkoZgXcHhCni83E43sRMKxEfc7sw2HCmJtDhYws0AJ4AESYTRBJgA7FY7odWYdMKoCHEGIc0Aw3ryEM0AFRs5JYpQELhfaJhE7M25s3kCAVhAhKjViiWYKUysJCPAAL2eJyphwArBouPL6Sy2RyucQeXyBcghcRRazxZhJWY9QwbXbWS71WrNZrvb7/QbjS8zVwAGyVMGBvGK%2B2c7nK/nqt0irU%2BnX%2Bf2ppUhw5h8NKyNF6NGk3%2BeMM5saVOMqm226YrwOQ7KbUEACyhiYwDi9KZIKVb1peGQFYYtDCz3Lb3QIBA50urwI65AmM%2Bv3%2BANIhzXG6JAdO5bzxGB/mwhxrBAUU7ZjIVVY/5jM/cL6utMwzFPD9SXJYhqVpJgN2faVZQYU90mNL51QgMlmAgmkmhggc4P1eslmOBkO2I0g301b8gL/SVDjMH8QKZMCMMg7CQGfP14MQ%2BsUMONDwJY6C2IHDj8ONQj23bMigw1SjfwHQ5/HooiLCYyksME59i04s9uNQ9C1KgnD/y00TMHE4iJOkiT/AVcizyaRx53Pfd4SvNwb3dK5DjHAhqJ1AB1QgEAiVhnggZyDyMI9AUOAkzLs79pKVLECHWHlnwUAA6WleLipZS3fCykWkmdHMOH5UDwdAnw%2BQRbloWg/JfCB8qsyckrZfhiF48smC8IhzATY5zQsOLT3QKCTHNM0QBq/8FFa9MKPapaq3svc0H6tEYVi0LttOdaN1cWgCuWjs2vO%2B4LJskEOBWWhOHNXg/A4LRSFQTg3GsawzzWDYTTBHhSAITQ7pWABrAJ/Ey/xYbh%2BH4YTfROEkZ7QfezheAUEANGB0GVjgWAkDQFhkjoOJyEoEmyfoeIfmQZJkl%2BLgEi%2BfxpVUBNpBoWhHWxiBonR%2BDKXRkm2EEAB5RcKXRrBziMcRXt4fAsR6H4fXRjlun6rYgbVWp0aXaJiEpDwsHR948BYTgeBWKgDGABQADVjwl5JGBt3h%2BEEEQxHYKQZEERQVHUJXSF0aYDCMFBvssfQ8GibHIBWVBknqbGOAAenPUxLGsMw3q6HpnAgVxJj8aYQmXeYRmmfIMgEcu8jSBuGDmYYKhqOpenGVpPHaPQi/qPoWnbspa5mCZ%2B6mSeBmrjuJBWBQ/s2PR3kwXW7uRjgntIF63o%2BjhOckQ4WAUenypZmGuF4r687jw5cEIEhjkB08PFJ8nup2Lgll4EGlZLAhlDGGCMwGwyRg9DgqM97o0PljHGeNAGkEJogEAawCDJH6pTCA1Mv4hTYJwY%2Bp9z7zh%2BFfdmvBMD4CIB8dc0xvbCFEOIAOjDg5qHRhHUgAITbJE9vdR6aMw6Hwlv1LB6pUBUEOMQs%2BF9yEJGvrfVAn9aav3Zn/JBWggGkEhrDUB4CEbbxgfvXg8DbCIIAVogRHAzBCIPpjTRYNSDq2IOkZwkggA%3D)

```auto
struct PresetManager
{
    static inline const std::map<std::string_view, std::span<const char>> presets
    {
        {"Preset 1", { BinaryData::preset1_bin, size_t (BinaryData::preset1_binSize) }},
        {"Preset 2", { BinaryData::preset2_bin, size_t (BinaryData::preset2_binSize) }},
        {"Preset 3", { BinaryData::preset3_bin, size_t (BinaryData::preset3_binSize) }}
    };

    static std::span<const char> getPresetWithName (std::string_view name)
    {
        return presets.at (name);
    }

    static void printAllPresets()
    {
        for (const auto& [name, data] : presets)
            std::cout << name << std::endl;
    }
};

```

I think it’s reasonable to keep a list like that up to date manually and using containers like e.g. `std::map` here gives you a lot of convenient functionality out of the box. Note that the code above could of course be rewritten using some JUCE classes – this was just a quick sketch that should compile on compiler explorer