Merge pull request #308 from scratchcpp/graphics_effects_api

Add API for graphics effects

Author: adazem009

CMakeLists.txt

@@ -51,6 +51,7 @@ target_sources(scratchcpp
     include/scratchcpp/iimageformat.h
     include/scratchcpp/iimageformatfactory.h
     include/scratchcpp/rect.h
+    include/scratchcpp/igraphicseffect.h
 )
 
 add_library(zip SHARED

docs/Graphics effects.md

@@ -0,0 +1,38 @@
+\page graphicsEffects Graphics effects
+
+libscratchcpp provides API for implementing custom graphics effects.
+No effects are currently included with libscratchcpp, but that is planned to change.
+
+In case you've implemented some of the effects yourself, feel free to make pull requests!
+These are the issues (tasks) for the default graphics effects:
+
+- Color: https://github.com/scratchcpp/libscratchcpp/issues/283
+- Fisheye: https://github.com/scratchcpp/libscratchcpp/issues/284
+- Whirl: https://github.com/scratchcpp/libscratchcpp/issues/285
+- Pixelate: https://github.com/scratchcpp/libscratchcpp/issues/286
+- Mosaic: https://github.com/scratchcpp/libscratchcpp/issues/287
+- Brightness: https://github.com/scratchcpp/libscratchcpp/issues/288
+- Ghost: https://github.com/scratchcpp/libscratchcpp/issues/289
+
+# Implementing a graphics effect
+To implement a graphics effect that libscratchcpp doesn't support,
+subclass \link libscratchcpp::IGraphicsEffect IGraphicsEffect \endlink
+and override all of the methods.
+
+It's recommended to use the libscratchcpp namespace like this in your class:
+```cpp
+using namespace libscratchcpp;
+```
+
+The `name()` method should return the name of the effect which is
+used by the set and change effect blocks, for example `ghost` or `fisheye`.
+
+The `apply()` method is used to apply the effect on a bitmap. The bitmap
+can be accessed using the `bitmap` parameter and is writable.
+
+# Registering the graphics effect
+To register the graphics effect, use \link libscratchcpp::ScratchConfiguration::registerGraphicsEffect() ScratchConfiguration::registerGraphicsEffect() \endlink.
+
+```cpp
+libscratchcpp::ScratchConfiguration::registerGraphicsEffect(std::make_shared<MyGraphicsEffect>());
+```

include/scratchcpp/costume.h

@@ -11,6 +11,7 @@ namespace libscratchcpp
 {
 
 class Broadcast;
+class IGraphicsEffect;
 class CostumePrivate;
 
 /*! \brief The Costume class represents a Scratch costume. */
@@ -40,6 +41,9 @@ class LIBSCRATCHCPP_EXPORT Costume : public Asset
 
         Rgb **bitmap() const;
 
+        double graphicsEffectValue(IGraphicsEffect *effect) const;
+        void setGraphicsEffectValue(IGraphicsEffect *effect, double value);
+
         Broadcast *broadcast();
 
     protected:

include/scratchcpp/igraphicseffect.h

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <string>
+
+#include "iimageformat.h"
+
+namespace libscratchcpp
+{
+
+/*! \brief The IGraphicsEffects class is an interface for implementing custom graphics effects. */
+class LIBSCRATCHCPP_EXPORT IGraphicsEffect
+{
+    public:
+        virtual ~IGraphicsEffect() { }
+
+        /*! Returns the name of the graphics effect. */
+        virtual std::string name() const = 0;
+
+        /*! Applies the effect on the given bitmap. */
+        virtual void apply(Rgb **bitmap, unsigned int width, unsigned int height, double value) const = 0;
+};
+
+} // namespace libscratchcpp

include/scratchcpp/scratchconfiguration.h

@@ -13,6 +13,7 @@ namespace libscratchcpp
 class IExtension;
 class IImageFormat;
 class IImageFormatFactory;
+class IGraphicsEffect;
 class ScratchConfigurationPrivate;
 
 /*! \brief The ScratchConfiguration class provides methods for adding custom extensions. */
@@ -41,6 +42,10 @@ class LIBSCRATCHCPP_EXPORT ScratchConfiguration
         static void removeImageFormat(const std::string &name);
         static std::shared_ptr<IImageFormat> createImageFormat(const std::string &name);
 
+        static void registerGraphicsEffect(std::shared_ptr<IGraphicsEffect> effect);
+        static void removeGraphicsEffect(const std::string &name);
+        static IGraphicsEffect *getGraphicsEffect(const std::string &name);
+
     private:
         static const std::vector<std::shared_ptr<IExtension>> getExtensions();
 

include/scratchcpp/sprite.h

@@ -9,6 +9,7 @@ namespace libscratchcpp
 
 class ISpriteHandler;
 class Rect;
+class IGraphicsEffect;
 class SpritePrivate;
 
 /*! \brief The Sprite class represents a Scratch sprite. */
@@ -65,6 +66,9 @@ class LIBSCRATCHCPP_EXPORT Sprite : public Target
 
         Rect boundingRect() const;
 
+        double graphicsEffectValue(IGraphicsEffect *effect) const;
+        void setGraphicsEffectValue(IGraphicsEffect *effect, double value);
+
     private:
         Target *dataSource() const override;
         void setXY(double x, double y);

src/scratch/costume.cpp

@@ -107,6 +107,32 @@ Rgb **Costume::bitmap() const
     return impl->bitmap;
 }
 
+/*! Returns the value of the given graphics effect. */
+double Costume::graphicsEffectValue(IGraphicsEffect *effect) const
+{
+    auto it = impl->graphicsEffects.find(effect);
+
+    if (it == impl->graphicsEffects.cend())
+        return 0;
+    else
+        return it->second;
+}
+
+/*! Sets the value of the given graphics effect (this is automatically set by the sprite). */
+void Costume::setGraphicsEffectValue(IGraphicsEffect *effect, double value)
+{
+    auto it = impl->graphicsEffects.find(effect);
+    bool update = ((it == impl->graphicsEffects.cend()) || (it->second != value));
+
+    if (value == 0)
+        impl->graphicsEffects.erase(effect);
+    else
+        impl->graphicsEffects[effect] = value;
+
+    if (update)
+        impl->updateImage();
+}
+
 /*!
  * Returns the Broadcast linked with this costume.
  * \note This is used by the "switch backdrop to and wait" block.

src/scratch/costume_p.cpp

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
+#include <scratchcpp/igraphicseffect.h>
+
 #include "costume_p.h"
 
 using namespace libscratchcpp;
@@ -37,15 +39,15 @@ void CostumePrivate::updateImage()
         oldHeight = scaledHeight;
     }
 
-    for (unsigned int i = 0; i < scaledHeight; i++) {
-        for (unsigned int j = 0; j < scaledWidth; j++) {
-            Rgb color = image->colorAt(mirrorHorizontally ? (scaledWidth - 1 - j) : j, i, scale / bitmapResolution);
-
-            // TODO: Apply graphics effects here
+    double actualScale = scale / bitmapResolution;
 
-            bitmap[i][j] = color;
-        }
+    for (unsigned int i = 0; i < scaledHeight; i++) {
+        for (unsigned int j = 0; j < scaledWidth; j++)
+            bitmap[i][j] = image->colorAt(mirrorHorizontally ? (scaledWidth - 1 - j) : j, i, actualScale);
     }
+
+    for (const auto &[effect, value] : graphicsEffects)
+        effect->apply(bitmap, scaledWidth, scaledHeight, value);
 }
 
 void CostumePrivate::freeImage()

src/scratch/costume_p.h

@@ -4,11 +4,12 @@
 
 #include <scratchcpp/broadcast.h>
 #include <scratchcpp/iimageformat.h>
+#include <unordered_map>
 
 namespace libscratchcpp
 {
 
-class IImageFormat;
+class IGraphicsEffect;
 
 struct CostumePrivate
 {
@@ -30,6 +31,7 @@ struct CostumePrivate
         double oldScale = 1;
         double scale = 1;
         bool mirrorHorizontally = false;
+        std::unordered_map<IGraphicsEffect *, double> graphicsEffects;
         Broadcast broadcast;
 };
 

src/scratch/sprite.cpp

@@ -212,6 +212,9 @@ void Sprite::setCurrentCostume(int newCostume)
     if (costume) {
         costume->setScale(impl->size / 100);
         costume->setMirrorHorizontally(impl->rotationStyle == RotationStyle::LeftRight);
+
+        for (const auto &[effect, value] : impl->graphicsEffects)
+            costume->setGraphicsEffectValue(effect, value);
     }
 
     Target::setCurrentCostume(newCostume);
@@ -309,6 +312,29 @@ Rect Sprite::boundingRect() const
     return ret;
 }
 
+/*! Returns the value of the given graphics effect. */
+double Sprite::graphicsEffectValue(IGraphicsEffect *effect) const
+{
+    auto it = impl->graphicsEffects.find(effect);
+
+    if (it == impl->graphicsEffects.cend())
+        return 0;
+    else
+        return it->second;
+}
+
+/*! Sets the value of the given graphics effect. */
+void Sprite::setGraphicsEffectValue(IGraphicsEffect *effect, double value)
+{
+    impl->graphicsEffects[effect] = value;
+
+    // TODO: Make currentCostume() return the costume (not index)
+    auto costume = costumeAt(currentCostume() - 1);
+
+    if (costume)
+        costume->setGraphicsEffectValue(effect, value);
+}
+
 Target *Sprite::dataSource() const
 {
     return impl->cloneRoot;

src/scratch/sprite_p.h

@@ -3,6 +3,7 @@
 #pragma once
 
 #include <scratchcpp/sprite.h>
+#include <unordered_map>
 
 namespace libscratchcpp
 {
@@ -32,6 +33,7 @@ struct SpritePrivate
         double direction = 90;
         bool draggable = false;
         Sprite::RotationStyle rotationStyle = Sprite::RotationStyle::AllAround;
+        std::unordered_map<IGraphicsEffect *, double> graphicsEffects;
 };
 
 } // namespace libscratchcpp

src/scratchconfiguration.cpp

@@ -2,6 +2,7 @@
 
 #include <scratchcpp/scratchconfiguration.h>
 #include <scratchcpp/iimageformatfactory.h>
+#include <scratchcpp/igraphicseffect.h>
 #include <iostream>
 
 #include "scratchconfiguration_p.h"
@@ -50,6 +51,32 @@ std::shared_ptr<IImageFormat> ScratchConfiguration::createImageFormat(const std:
         return it->second->createInstance();
 }
 
+/*! Registers the given graphics effect. */
+void ScratchConfiguration::registerGraphicsEffect(std::shared_ptr<IGraphicsEffect> effect)
+{
+    if (!effect)
+        return;
+
+    impl->graphicsEffects[effect->name()] = effect;
+}
+
+/*! Removes the given graphics effect. */
+void ScratchConfiguration::removeGraphicsEffect(const std::string &name)
+{
+    impl->graphicsEffects.erase(name);
+}
+
+/*! Returns the graphics effect with the given name, or nullptr if it isn't registered. */
+IGraphicsEffect *ScratchConfiguration::getGraphicsEffect(const std::string &name)
+{
+    auto it = impl->graphicsEffects.find(name);
+
+    if (it == impl->graphicsEffects.cend())
+        return nullptr;
+    else
+        return it->second.get();
+}
+
 const std::vector<std::shared_ptr<IExtension>> ScratchConfiguration::getExtensions()
 {
     return impl->extensions;

src/scratchconfiguration_p.h

@@ -14,6 +14,7 @@ namespace libscratchcpp
 
 class IExtension;
 class IImageFormatFactory;
+class IGraphicsEffect;
 
 struct ScratchConfigurationPrivate
 {
@@ -22,6 +23,7 @@ struct ScratchConfigurationPrivate
 
         std::vector<std::shared_ptr<IExtension>> extensions = { std::make_shared<StandardBlocks>() };
         std::unordered_map<std::string, std::shared_ptr<IImageFormatFactory>> imageFormats;
+        std::unordered_map<std::string, std::shared_ptr<IGraphicsEffect>> graphicsEffects;
 };
 
 } // namespace libscratchcpp