Q: How can I use libjpeg to encode directly to memory on my embedded system without using a file?

A: If you’re encoding images into JPEG on your ARM/Linux embedded platform then you’re most likely using libjpeg, and if you’re encoding quickly then you’re most likely using its drop-in replacement libjpeg-turbo!

Most of the examples of how to use the libjpeg API show how to encode directly to a file, but it’s also possible to use the API to encode to a memory buffer instead. This is handy if you want to transmit the JPEG via MQTT or something and don’t actually need a JPEG file – you can avoid the overhead of writing to your flash filesystem and having to read the data from it before sending.

Of course, one easy way of achieving this if your embedded system has a RAM disk (as a lot of ARM/Linux based systems will) is to just get libjpeg to encode to file on the RAM disk, in this way you can avoid writing to flash, however you will still have to open the file and read in all of the data into a buffer afterwards.

The trick to getting libjpeg to encode directly to  memory is make a call to jpeg_mem_dest() (instead of to jpeg_stdio_dest() for a file), this allows the caller to specify an output buffer for the jpeg data (as well as its size).

You can either supply a pointer to a buffer, or if you pass NULL, the library will allocate a buffer for you – either way, you must free() the output buffer once you are finished with it!

Some things to note are:

• You can pass in a pointer to a buffer that you have already malloc()’ed
• If you pass in NULL, the lib will allocate a buffer for you.
• If the buffer that you specify (or that the lib automatically malloced()’ed) turns out to be too small to hold the JPEG data then the lib will free() the buffer and malloc() a new one (this will probably also involve a memory copy).
• After encoding the size variable will contain the number of JPEG bytes in the output buffer (i.e. it no longer contains the size of the buffer used!)
• If you want to re-use the same buffer for each encode, then just pass in the same buffer pointer each time with it’s original size and don’t free() it after encoding.

Here is an example of a c++ function that encodes to memory, it uses a buffer that’s allocated by the library:

//
// Encodes a 256 Greyscale image to JPEG directly to a memory buffer
// libJEPG will malloc() the buffer so the caller must free() it when
// they are finished with it.
//
// image    - the input greyscale image, 1 byte is 1 pixel.
// width    - the width of the input image
// height   - the height of the input image
// quality  - target JPEG 'quality' factor (max 100)
// comment  - optional JPEG NULL-termoinated comment, pass NULL for no comment.
// jpegSize - output, the number of bytes in the output JPEG buffer
// jpegBuf  - output, a pointer to the output JPEG buffer, must call free() when finished with it.
//
void encode_jpeg_to_memory(unsigned char* image, int width, int height, int quality,
                            const char* comment, unsigned long* jpegSize, unsigned char** jpegBuf) {
    struct jpeg_compress_struct cinfo;
    struct jpeg_error_mgr jerr;
    JSAMPROW row_pointer[1];
    int row_stride;
    cinfo.err = jpeg_std_error(&jerr);
    jpeg_create_compress(&cinfo);
    cinfo.image_width = width;
    cinfo.image_height = height;
    // Input is greyscale, 1 byte per pixel
    cinfo.input_components = 1;
    cinfo.in_color_space = JCS_GRAYSCALE;
    jpeg_set_defaults(&cinfo);
    jpeg_set_quality(&cinfo, quality, TRUE);
    //
    //
    // Tell libJpeg to encode to memory, this is the bit that's different!
    // Lib will alloc buffer.
    //
    jpeg_mem_dest(&cinfo, jpegBuf, jpegSize);
    jpeg_start_compress(&cinfo, TRUE);
    // Add comment section if any..
    if (comment) {
        jpeg_write_marker(&cinfo, JPEG_COM, (const JOCTET*)comment, strlen(comment));
    }
    // 1 BPP
    row_stride = width;
    // Encode
    while (cinfo.next_scanline < cinfo.image_height) {
        row_pointer[0] = &image[cinfo.next_scanline * row_stride];
        jpeg_write_scanlines(&cinfo, row_pointer, 1);
    }
    jpeg_finish_compress(&cinfo);
    jpeg_destroy_compress(&cinfo);
}

The we can use this function to encode an 8bit image like this:

void test_encode_jpeg_to_memory() {
    int width = 1920;
    int height = 1080;
    // Create an 8bit greyscale image
    unsigned char* image = (unsigned char*)malloc(width * height);
    // With a pattern
    for (int j = 0; j != height; j++) {
        for (int i = 0; i != width; i++)
            image[i + j * width] = i + j;
    }
    // Will hold encoded size
    unsigned long jSize = 0;
    // Will point to JPEG buffer
    unsigned char* jBuf = NULL;
    // Encode image
    encode_jpeg_to_memory(image, width, height, 85, "A Comment!", &jSize, &jBuf);
    printf("JPEG size (bytes): %ld", jSize);
    //
    // Now, do something with the JPEG image in jBuf like stream it over UDP or sommit!
    //
    // Free jpeg memory
    free(jBuf);
    // Free original image
    free(image);
}

So I had a problem, as part of an embedded software system I was working on I needed to periodically send some GPS information via UDP datagrams to other devices on the network – really simple stuff, transmit a string to an IP address on a given port, Fire And Forget, send a string from here to there – end of story!

Now my normal port of call these days for networking in C++ is to reach for the boost::asio libs, as mentioned here, this library is very powerful and flexible and can handle a huge number of different networking scenarios.

All well and good, but sometimes I wish that I could just call a simple function and not have to remember or worry about all of boost stuff as it can be a proper head-wreck and there’s a lot of typing as the namespaces are so long! Python has me really spoiled, it makes so many things simple and easy to use!

So I wrote a little C++ wrapper class that just has 1 function called send() that can send a string or the contents of a binary buffer, the class is called: boost_udp_send_faf (faf stands for Fire-and-Forget!).

It is a very basic wrapper around the boost libs and only handles very simple transmission use-cases, but these use-cases probably cover about 80% of my UDP transmission needs!

To use the class for a single Fire-and-Forget send:

//
#include "boost_udp_send_faf.h"
boost_udp_send_faf("192.168.1.44", 8861).send("The message!");
//

This sends the message to 192.168.1.44 on port 8861.

If your program needs send multiple datagrams, then we can keep the socket open and reuse the end-point like this:

//
#include "boost_udp_send_faf.h"
boost_udp_send_faf sender("192.168.1.44", 8861);
for (auto i = 0; i != 10; i++) { sender.send("Lots of messages! :-/"); }
//

The socket will remain open until the ‘sender’ object goes out of scope.

It’s probably best to add exception handling to your calls as they can fail for lots of reasons and as ever networking is very flaky & unpredictable.

//
try {
    boost_udp_send_faf("192.168.1.44", 8861).send("The message!");
} catch (const boost::system::system_error& ex) { cerr << "Send failed: " << ex.what(); }
//

This will also ensure that the socket is closed once the message is sent as the object will go out of scope when execution leaves the try block.

The code for boost_udp_send_faf can be found in this repo on GitHub, but I have in-lined it below as well.

For an easier way to receive UDP data see: boost_udp_receive_rar

#pragma once
//   Copyright 2018 Kevin Godden
//
//   Licensed under the Apache License, Version 2.0 (the "License");
//   you may not use this file except in compliance with the License.
//   You may obtain a copy of the License at
//
//       http://www.apache.org/licenses/LICENSE-2.0
//
//   Unless required by applicable law or agreed to in writing, software
//   distributed under the License is distributed on an "AS IS" BASIS,
//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//   See the License for the specific language governing permissions and
//   limitations under the License.
#include <boost/asio.hpp>
#include <string>
//
// Fire-and-Forget (FAF) transmission for UDP
// using the boost::asio lib. Very simple wrapper
// around the boost libs.
//
// Can throw the following exception:
//	boost::system::system_error
//
// Synopsis --->
//
// For a single Fire-and-Forget send:
//
// #include "boost_udp_send_faf.h"
//
// boost_udp_send_faf("192.168.1.44", 8861).send("The message!");
//
//
// To send multiple datagrams while keeping the socket open and
// reusing end-point:
//
// #include "boost_udp_send_faf.h"
//
// boost_udp_send_faf sender("192.168.1.44", 8861);
//		
// for (auto i = 0; i != 10; i++) {
//     sender.send("Lots of messages! :-/");
// }
//
// The socket will remain open while the boost_udp_send_faf object is in scope
// so to control when the socket is closed, control the scope of the object.
//
// If you want to do anything fancy like using scatter-gather buffers etc. then
// just use the boost libs!  This is for real simple stuff!
//

class boost_udp_send_faf {
    boost::asio::io_service io_service;
    boost::asio::ip::udp::socket socket;
    boost::asio::ip::udp::endpoint remote_endpoint;
public:
    boost_udp_send_faf(const std::string& ip_address, const int port, const bool broadcast = false) : socket(io_service) {
        
        // Open socket
        socket.open(boost::asio::ip::udp::v4());
        // I wouldn't recommend broadcasting unless you are
        // in complete control of your subnet and know
        // what's on it and how it will react
        if (broadcast) {
            boost::asio::socket_base::broadcast option(true);
            socket.set_option(option);
        }
        // make endpoint
        remote_endpoint = boost::asio::ip::udp::endpoint(boost::asio::ip::address::from_string(ip_address.c_str()), port);
    }
    // Send a string to the preconfigured endpoint
    // via the open socket.
    void send(const std::string& message) {
        boost::system::error_code ignored_error;
        socket.send_to(boost::asio::buffer(message), remote_endpoint, 0, ignored_error);
    }
    // Send some binary data to the preconfigured endpoint
    // via the open socket.
    void send(const unsigned char* data, const int len) {
        boost::system::error_code ignored_error;
        socket.send_to(boost::asio::buffer(data, len), remote_endpoint, 0, ignored_error);
    }
};

The Mod/Modulo (% in C) operator is incredibly useful in many situations, it calculates the remainder from an integer division, for example 10 Mod 3 = 1 (10 Div 3 = 3, 3 * 3 = 9, 10 – 9 = 1).

Although you can happily call the % operator from your embedded C program it is important to be aware that it is typically implemented using integer division and multiplication, which is fine if your embedded system support these in hardware, if not they will be implemented in software sometimes resulting in huge time penalties (for example, on many PIC chips).

Often this won’t be a problem, but if you’re programming a real-time system these delays can be devastating! A big sting-in-the-tail from an innocent looking operator %

So what can be done:

a.) Avoid using % in your time-sensitive code, perhaps use running sums and remainders instead.

b.) Use a power-of-2 in your Mod call instead.

If the value of the right-hand operator isn’t crucial and both arguments are positive, then switching to a power of 2 will make it much easier and faster to calculate, a power-of-2 Mod can be calculated with an AND instruction.

a % b == a & (b - 1)    // if b is a power of 2 and a, b are both +ve.

Your compiler should figure out that you are using a power-of-2 and automatically carry out the optimisation, but to be safe, check the output assembly code. If it hasn’t optimised then you can replace your code with a & (b – 1)

If you’re using the very handy boost::split() on Visual Studio, then you may run into the following annoying warning:

warning C4996: ‘std::copy::_Unchecked_iterators::_Deprecate’: Call to ‘std::copy’ with parameters that may be unsafe – this call relies on the caller to check that the passed values are correct. To disable this warning, use -D_SCL_SECURE_NO_WARNINGS. See documentation on how to use Visual C++ ‘Checked Iterators’

It’s a big warning that rightly litters the compiler’s output!!

Everything’s OK, it’s just VS whinging about std::copy() being called with pointers. As the warning mentions, you can disable the warnings by defining _SCL_SECURE_NO_WARNINGS, its probably best to define it only for the affected files and not your whole project however!

Another way is to explicitly instruct that warning 4996 be ignored in the code like this:

//
// Suppress annoying warning for boost:split()
//
#if defined(_MSC_VER) && _MSC_VER >= 1400 
#pragma warning(push) 
#pragma warning(disable:4996) 
#endif 
#include 
#if defined(_MSC_VER) && _MSC_VER >= 1400 
#pragma warning(pop) 
//

More Info