Sprite store API

src/mbgl/annotation/sprite_image.cpp

@@ -0,0 +1,27 @@
+#include <mbgl/annotation/sprite_image.hpp>
+
+#include <mbgl/util/exception.hpp>
+
+#include <cmath>
+
+namespace mbgl {
+
+SpriteImage::SpriteImage(const uint16_t width_,
+                         const uint16_t height_,
+                         const float ratio_,
+                         std::string&& data_)
+    : width(width_),
+      height(height_),
+      ratio(ratio_),
+      pixelWidth(std::ceil(width * ratio)),
+      pixelHeight(std::ceil(height * ratio)),
+      data(std::move(data_)) {
+    const size_t size = pixelWidth * pixelHeight * 4;
+    if (size == 0) {
+        throw util::SpriteImageException("Sprite image dimensions may not be zero");
+    } else if (size != data.size()) {
+        throw util::SpriteImageException("Sprite image pixel count mismatch");
+    }
+}
+
+} // namespace mbgl

src/mbgl/annotation/sprite_image.hpp

@@ -0,0 +1,36 @@
+#ifndef MBGL_ANNOTATIONS_SPRITE_IMAGE
+#define MBGL_ANNOTATIONS_SPRITE_IMAGE
+
+#include <mbgl/util/noncopyable.hpp>
+#include <mbgl/util/geo.hpp>
+
+#include <string>
+#include <memory>
+#include <cstdint>
+
+namespace mbgl {
+
+class SpriteImage : private util::noncopyable {
+public:
+    SpriteImage(uint16_t width, uint16_t height, float ratio, std::string&& data);
+
+    // Logical dimensions of the sprite image.
+    const uint16_t width;
+    const uint16_t height;
+
+    // Pixel ratio of the sprite image.
+    const float ratio;
+
+    // Physical dimensions of the sprite image.
+    const uint16_t pixelWidth;
+    const uint16_t pixelHeight;
+
+    // A string of an RGBA8 representation of the sprite. It must have exactly
+    // (width * ratio) * (height * ratio) * 4 (RGBA) bytes. The scan lines may
+    // not have gaps between them (i.e. stride == 0).
+    const std::string data;
+};
+
+}
+
+#endif

src/mbgl/annotation/sprite_store.cpp

@@ -0,0 +1,40 @@
+#include <mbgl/annotation/sprite_store.hpp>
+
+#include <mbgl/util/exception.hpp>
+
+namespace mbgl {
+
+SpriteStore::SpriteStore(const float ratio_) : ratio(ratio_) {
+}
+
+void SpriteStore::setSprite(const std::string& name, std::shared_ptr<const SpriteImage> sprite) {
+    if (sprite && sprite->ratio != ratio) {
+        throw util::SpriteImageException("Sprite image has wrong pixel ratio");
+    }
+    std::lock_guard<std::mutex> lock(mutex);
+    if (sprite) {
+        sprites.emplace(name, sprite);
+    } else {
+        sprites.erase(name);
+    }
+    dirty.emplace(name, sprite);
+}
+
+void SpriteStore::removeSprite(const std::string& name) {
+    setSprite(name);
+}
+
+std::shared_ptr<const SpriteImage> SpriteStore::getSprite(const std::string& name) {
+    std::lock_guard<std::mutex> lock(mutex);
+    const auto it = sprites.find(name);
+    return it != sprites.end() ? it->second : nullptr;
+}
+
+SpriteStore::Sprites SpriteStore::getDirty() {
+    Sprites result;
+    std::lock_guard<std::mutex> lock(mutex);
+    dirty.swap(result);
+    return result;
+}
+
+} // namespace mbgl

src/mbgl/annotation/sprite_store.hpp

@@ -0,0 +1,52 @@
+#ifndef MBGL_ANNOTATION_SPRITE_STORE
+#define MBGL_ANNOTATION_SPRITE_STORE
+
+#include <mbgl/annotation/sprite_image.hpp>
+
+#include <mbgl/util/noncopyable.hpp>
+#include <mbgl/util/geo.hpp>
+
+#include <map>
+#include <set>
+#include <vector>
+#include <memory>
+#include <mutex>
+#include <cstdint>
+
+namespace mbgl {
+
+// The SpriteStore object holds Sprite images.
+class SpriteStore : private util::noncopyable {
+    using Sprites = std::map<std::string, std::shared_ptr<const SpriteImage>>;
+
+public:
+    SpriteStore(const float ratio);
+
+    // Adds/replaces a Sprite image.
+    void setSprite(const std::string&, std::shared_ptr<const SpriteImage> = nullptr);
+
+    // Removes a Sprite.
+    void removeSprite(const std::string&);
+
+    // Obtains a Sprite image.
+    std::shared_ptr<const SpriteImage> getSprite(const std::string&);
+
+    // Returns Sprite images that changed since the last invocation of this function.
+    Sprites getDirty();
+
+private:
+    const float ratio;
+
+    // Lock for sprites and dirty maps.
+    std::mutex mutex;
+
+    // Stores all current sprites.
+    Sprites sprites;
+
+    // Stores all Sprite IDs that changed since the last invocation.
+    Sprites dirty;
+};
+
+} // namespace mbgl
+
+#endif

src/mbgl/geometry/sprite_atlas.hpp

@@ -46,8 +46,10 @@ public:
     // This getter attempts to read the image from the sprite if it is already loaded.
     // In that case, it copies it into the sprite atlas and returns the dimensions.
     // Otherwise, it returns a 0/0/0/0 rect.
+    // This function is used during bucket creation.
     Rect<dimension> getImage(const std::string& name, const bool wrap);
 
+    // This function is used for getting the position during render time.
     SpriteAtlasPosition getPosition(const std::string& name, bool repeating = false);
 
     // Binds the atlas texture to the GPU, and uploads data if it is out of date.