Program Listing for File Texture.h#
↰ Return to documentation for file (include/Karana/Scene/Texture.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
/**
* @file
* @brief Contains the declarations for the Texture and GrayscaleTexture classes.
*/
#pragma once
#include "Karana/KCore/Base.h"
#include <filesystem>
#include <unsupported/Eigen/CXX11/Tensor>
namespace Karana::Scene {
namespace fs = std::filesystem;
namespace kc = Karana::Core;
/** This is the TextureData type. It is a rank 3 tensor. The first two values are the
* width and height of the data. The last value is the number of elements in the data,
* e.g., 3 for RGB, 4 for RGBA, etc.
*/
using TextureData = Eigen::Tensor<uint8_t, 3, Eigen::RowMajor>;
/**
* @class Texture
* @brief Class for a texture image
*
* See \sref{scene_layer_sec} for more discussion on
* the scene layer.
*/
class Texture : public Karana::Core::Base {
public:
/**
* @brief Texture constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The Texture's name.
* @param data_in Input data to create the Texture.
*/
Texture(std::string_view name, const TextureData &data_in);
/**
* @brief Destructor for Texture.
*/
~Texture();
/**
* @brief Create a Texture instance.
* @param name The Texture's name.
* @param data The data for the texture.
* @return A ks_ptr to the Texture.
*/
static kc::ks_ptr<Texture> create(std::string_view name, const TextureData &data);
/**
* @brief Create a Texture instance.
* @param name The Texture's name.
* @param buffer A buffer holding a compressed image format.
* @param len The length of the buffer.
* @return A ks_ptr to the Texture.
*/
static kc::ks_ptr<Texture> create(std::string_view name, unsigned char *buffer, int len);
/**
* @brief Create a texture from a file name. This caches the texture
* so that future versions created with the same file name
* just return a pointer to the same texture.
* @param filename The name of the file.
* @return A ks_ptr to the Texture.
*/
static kc::ks_ptr<Texture> lookupOrCreateTexture(const std::filesystem::path &filename);
/**
* @brief Write the texture to a file.
* @param filename The name of the file to write to.
*/
void writeToFile(const std::filesystem::path &filename);
/**
* @brief Write the texture to a png stream.
* @return The png stream as an std::vector of unsigned char*
*/
std::vector<unsigned char> writeToPngMem() const;
/**
* @brief Get the texture data associated with the Texture.
* @return The texture data associated with the Texture.
*/
const TextureData &getData() const;
/**
* @brief Set the texture data associated with the Texture.
* @param data The data to set the Texture data to.
*/
virtual void setData(const TextureData &data);
/**
* @brief Set the texture data associated with the Texture.
* @param data The data to set the Texture data to.
*/
virtual void setData(TextureData &&data);
protected:
/// Holds the data for the texture
TextureData _data;
private:
static std::unordered_map<fs::path, kc::id_t> _texture_cache;
};
/**
* @class GrayscaleTexture
* @brief Texture specialization for grayscale values
*
* See \sref{scene_layer_sec} for more discussion on
* the scene layer.
*/
class GrayscaleTexture : public Texture {
public:
/**
* @brief GrayscaleTexture constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The Texture's name.
* @param data_in Input data to create the Texture.
*/
GrayscaleTexture(std::string_view name, const TextureData &data_in);
/**
* @brief Destructor for GrayscaleTexture.
*/
~GrayscaleTexture();
/**
* @brief Set the texture data associated with the Texture.
* @param data_in The data to set the Texture data to.
*/
void setData(const TextureData &data_in) final;
/**
* @brief Set the texture data associated with the Texture.
* @param data The data to set the Texture data to.
*/
virtual void setData(TextureData &&data);
/**
* @brief Create a GrayscaleTexture instance.
* @param name The Texture's name.
* @param data The data for the texture.
* @return A ks_ptr to the GrayscaleTexture.
*/
// Adding suppression, as CodeChecker complains this method has the same name as a method in
// the base version. This is just a CodeChecker false positive.
// codechecker_suppress [cppcheck-duplInheritedMember]
static kc::ks_ptr<GrayscaleTexture> create(std::string_view name, const TextureData &data);
/**
* @brief Create a GrayscaleTexture instance.
* @param name The Texture's name.
* @param buffer A buffer holding a compressed image format.
* @param len The length of the buffer.
* @return A ks_ptr to the GrayscaleTexture.
*/
static kc::ks_ptr<GrayscaleTexture>
// Adding suppression, as CodeChecker complains this method has the same name as a method in
// the base version. This is just a CodeChecker false positive.
// codechecker_suppress [cppcheck-duplInheritedMember]
create(std::string_view name, unsigned char *buffer, int len);
/**
* @brief Create a texture from a file name. This caches the texture
* so that future versions created with the same file name
* just return a pointer to the same texture.
* @param filename The name of the file.
* @return A ks_ptr to the GrayscaleTexture.
*/
static kc::ks_ptr<GrayscaleTexture>
lookupOrCreateGrayscaleTexture(const std::filesystem::path &filename);
private:
static std::unordered_map<fs::path, kc::id_t> _grayscale_texture_cache;
};
} // namespace Karana::Scene