Merge pull request #281 from scratchcpp/image_api

Add image format API

Author: adazem009

CMakeLists.txt

@@ -48,6 +48,8 @@ target_sources(scratchcpp
     include/scratchcpp/sprite.h
     include/scratchcpp/itimer.h
     include/scratchcpp/keyevent.h
+    include/scratchcpp/iimageformat.h
+    include/scratchcpp/iimageformatfactory.h
 )
 
 add_library(zip SHARED

Doxyfile

@@ -975,6 +975,7 @@ EXCLUDE_SYMLINKS       = NO
 
 EXCLUDE_PATTERNS       = */internal/* \
                          */src/blocks/* \
+                         */src/imageformats/* \
                          *_p.cpp \
                          *_p.h
 

docs/Image formats.md

@@ -0,0 +1,33 @@
+\page imageFormats Image formats
+
+To work with costumes, libscratchcpp has to read image files from Scratch projects.
+No formats are currently supported, but that will change soon.
+
+# Implementing a custom image format
+To implement a custom image format that libscratchcpp doesn't support,
+subclass \link libscratchcpp::IImageFormat IImageFormat \endlink
+and override all of the methods.
+
+Then subclass \link libscratchcpp::IImageFormatFactory IImageFormatFactory \endlink
+and override \link libscratchcpp::IImageFormatFactory::createInstance() createInstance() \endlink.
+
+It's recommended to use the libscratchcpp namespace like this in your classes:
+```cpp
+using namespace libscratchcpp;
+```
+
+Here's an example of the `createInstance()` method:
+```cpp
+std::shared_ptr<IImageFormat> TiffImageFormatFactory::createInstance() {
+    return std::make_shared<TiffImageFormat>();
+}
+```
+
+# Registering the image format
+To register the image format, you need to register the factory class.
+It will be used by classes such as \link libscratchcpp::Costume Costume \endlink
+internally to instantiate your image format.
+
+```cpp
+libscratchcpp::ScratchConfiguration::registerImageFormat("tiff", std::make_shared<TiffImageFormatFactory>());
+```

include/scratchcpp/asset.h

@@ -28,6 +28,12 @@ class LIBSCRATCHCPP_EXPORT Asset : public Entity
 
         const std::string &dataFormat() const;
 
+        const char *data() const;
+        void setData(const char *data);
+
+    protected:
+        virtual void processData(const char *data) { }
+
     private:
         spimpl::unique_impl_ptr<AssetPrivate> impl;
 };

include/scratchcpp/costume.h

@@ -2,6 +2,7 @@
 
 #pragma once
 
+#include "iimageformat.h"
 #include "spimpl.h"
 
 #include "asset.h"
@@ -28,8 +29,22 @@ class LIBSCRATCHCPP_EXPORT Costume : public Asset
         int rotationCenterY() const;
         void setRotationCenterY(int newRotationCenterY);
 
+        unsigned int width() const;
+        unsigned int height() const;
+
+        double scale() const;
+        void setScale(double scale);
+
+        bool mirrorHorizontally() const;
+        void setMirrorHorizontally(bool mirror);
+
+        Rgb **bitmap() const;
+
         Broadcast *broadcast();
 
+    protected:
+        void processData(const char *data) override;
+
     private:
         spimpl::unique_impl_ptr<CostumePrivate> impl;
 };

include/scratchcpp/iimageformat.h

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "global.h"
+
+namespace libscratchcpp
+{
+
+/*! A typedef for unsigned int. Holds the RGBA values. */
+using Rgb = unsigned int;
+
+/*! \brief The IImageFormat class is an interface for image format implementation. */
+class LIBSCRATCHCPP_EXPORT IImageFormat
+{
+    public:
+        virtual ~IImageFormat() { }
+
+        /*! Sets the image data (buffer). */
+        virtual void setData(const char *data) = 0;
+
+        /*! Returns the width of the image. */
+        virtual unsigned int width() const = 0;
+
+        /*! Returns the height of the image. */
+        virtual unsigned int height() const = 0;
+
+        /*! Returns the color at the given pixel. */
+        virtual Rgb colorAt(unsigned int x, unsigned int y, double scale = 1) const = 0;
+};
+
+} // namespace libscratchcpp

include/scratchcpp/iimageformatfactory.h

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <memory>
+
+#include "global.h"
+
+namespace libscratchcpp
+{
+
+class IImageFormat;
+
+/*! \brief The IImageFormatFactory class is an interface which is used to instantiate image formats. */
+class LIBSCRATCHCPP_EXPORT IImageFormatFactory
+{
+    public:
+        virtual ~IImageFormatFactory() { }
+
+        /*! Creates an instance of the image format. */
+        virtual std::shared_ptr<IImageFormat> createInstance() const = 0;
+};
+
+} // namespace libscratchcpp

include/scratchcpp/scratchconfiguration.h

@@ -11,6 +11,8 @@ namespace libscratchcpp
 {
 
 class IExtension;
+class IImageFormat;
+class IImageFormatFactory;
 class ScratchConfigurationPrivate;
 
 /*! \brief The ScratchConfiguration class provides methods for adding custom extensions. */
@@ -35,6 +37,10 @@ class LIBSCRATCHCPP_EXPORT ScratchConfiguration
             return nullptr;
         };
 
+        static void registerImageFormat(const std::string &name, std::shared_ptr<IImageFormatFactory> formatFactory);
+        static void removeImageFormat(const std::string &name);
+        static std::shared_ptr<IImageFormat> createImageFormat(const std::string &name);
+
     private:
         static const std::vector<std::shared_ptr<IExtension>> getExtensions();
 

include/scratchcpp/sprite.h

@@ -47,6 +47,8 @@ class LIBSCRATCHCPP_EXPORT Sprite : public Target
         double size() const;
         void setSize(double newSize);
 
+        void setCurrentCostume(int newCostume);
+
         double direction() const;
         void setDirection(double newDirection);
 

src/CMakeLists.txt

@@ -12,3 +12,4 @@ add_subdirectory(blocks)
 add_subdirectory(engine)
 add_subdirectory(internal)
 add_subdirectory(scratch)
+add_subdirectory(imageformats)