magnum/src/Magnum/Text/GlyphCache.h

#ifndef Magnum_Text_GlyphCache_h
#define Magnum_Text_GlyphCache_h
/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
                2020, 2021, 2022, 2023 Vladimír Vondruš <mosra@centrum.cz>

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

/** @file
 * @brief Class @ref Magnum::Text::GlyphCache
 */

#include "Magnum/configure.h"

#ifdef MAGNUM_TARGET_GL
#include "Magnum/GL/Texture.h"
#include "Magnum/Text/AbstractGlyphCache.h"

namespace Magnum { namespace Text {

/**
@brief Glyph cache

Contains font glyphs rendered into a texture atlas.

@section Text-GlyphCache-usage Usage

Create the @ref GlyphCache object with sufficient size and then call
@ref AbstractFont::createGlyphCache() to fill it with glyphs.

@snippet Text-gl.cpp GlyphCache-usage

See the @ref Renderer class for information about text rendering. The
@ref AbstractGlyphCache base class has more information about general glyph
cache usage.

@todo Some way for Font to negotiate or check internal texture format
@todo Default glyph 0 with rect 0 0 0 0 will result in negative dimensions when
    nonzero padding is removed

@note This class is available only if Magnum is compiled with
    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
    for more information.
*/
class MAGNUM_TEXT_EXPORT GlyphCache: public AbstractGlyphCache {
    public:
        /**
         * @brief Constructor
         * @param internalFormat    Internal texture format
         * @param originalSize      Unscaled glyph cache texture size in pixels
         * @param size              Actual glyph cache texture size in pixels
         * @param padding           Padding around every glyph in pixels
         *
         * All glyphs parameters are saved relative to @p originalSize,
         * although the actual glyph cache texture has @p size. Glyph
         * @p padding can be used to account for e.g. glyph shadows.
         */
        explicit GlyphCache(GL::TextureFormat internalFormat, const Vector2i& originalSize, const Vector2i& size, const Vector2i& padding);

        /**
         * @brief Constructor
         *
         * Same as calling the above with @p originalSize and @p size being set
         * to the same value.
         */
        explicit GlyphCache(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& padding = {});

        /**
         * @brief Constructor
         *
         * Sets the internal texture format to single-channel. On OpenGL ES
         * 3.0+ and WebGL 2 uses @ref GL::TextureFormat::R8. On desktop OpenGL
         * requires @gl_extension{ARB,texture_rg} (also part of OpenGL 3.0). On
         * ES2 and WebGL 1 unconditionally uses @ref GL::TextureFormat::Luminance.
         * This is done for consistency with @ref GL::pixelFormat(), which
         * unconditionally returns @ref GL::PixelFormat::Luminance for
         * @ref PixelFormat::R8Unorm. See
         * @ref GlyphCache(GL::TextureFormat, const Vector2i&, const Vector2i&)
         * for an alternative.
         */
        explicit GlyphCache(const Vector2i& originalSize, const Vector2i& size, const Vector2i& padding);

        /**
         * @brief Constructor
         *
         * Same as calling the above with @p originalSize and @p size being set
         * to the same value.
         */
        explicit GlyphCache(const Vector2i& size, const Vector2i& padding = {});

        /**
         * @brief Construct without creating the internal state and the OpenGL texture object
         * @m_since_latest
         *
         * The constructed instance is equivalent to moved-from state, i.e. no
         * APIs can be safely called on the object. Useful in cases where you
         * will overwrite the instance later anyway. Move another object over
         * it to make it useful.
         *
         * This function can be safely used for constructing (and later
         * destructing) objects even without any OpenGL context being active.
         * However note that this is a low-level and a potentially dangerous
         * API, see the documentation of @ref NoCreate for alternatives.
         */
        explicit GlyphCache(NoCreateT) noexcept;

        /** @brief Cache texture */
        GL::Texture2D& texture() { return _texture; }

    #ifdef DOXYGEN_GENERATING_OUTPUT
    private:
    #else
    protected:
    #endif
        GL::Texture2D _texture;

    private:
        MAGNUM_TEXT_LOCAL GlyphCacheFeatures doFeatures() const override;
        MAGNUM_TEXT_LOCAL void doSetImage(const Vector2i& offset, const ImageView2D& image) override;
};

}}
#else
#error this header is available only in the OpenGL build
#endif

#endif