Add basic Archive flags for configuring archiving

Signed-off-by: Kevin Wheatley <kevin.wheatley@framestore.com>

Author: KevinJW

docs/api/constants.rst

@@ -47,6 +47,14 @@ These environmental variables are used by the OpenColorIO library
          Ex: OCIO_OPTIMIZATION_FLAGS="20479" or "0x4FFF" for 
          OPTIMIZATION_LOSSLESS.
 
+      .. data:: PyOpenColorIO.OCIO_ARCHIVE_FLAGS_ENVVAR
+
+         The envvar 'OCIO_ARCHIVE_FLAGS' provides a way to modify the parameters
+         used to create an ocioz archive. Remove the variable or set the value
+         to empty to not use it. Set the value of the variable to the desired
+         parameters as either an integer or hexadecimal value.
+         Ex: OCIO_ARCHIVE_FLAGS="256" or "0x0100" for ARCHIVE_FLAGS_MINIMAL.
+
    .. group-tab:: C++
 
       .. doxygengroup:: VarsEnvvar

include/OpenColorIO/OpenColorIO.h

@@ -1524,15 +1524,18 @@ class OCIOEXPORT Config
      * trying to resolve all the FileTransforms in the Config to specific files is because of the
      * goal to allow context variables to continue to work.
      * 
+     * Archiving a minimal Config will try resolve these file references using the current context.
+     *
      * If a Config is created with CreateFromStream, CreateFromFile with an OCIOZ archive, or 
      * CreateFromConfigIOProxy, it cannot be archived unless the working directory is manually set 
      * to a directory that contains any necessary LUT files. 
      * 
      * The provided output stream must be closed by the caller, if necessary (e.g., an ofstream).
      *
      * \param ostream The output stream to write to.
+     * \param flags Flags top control archive creation
      */
-    void archive(std::ostream & ostream) const;
+    void archive(std::ostream & ostream, ArchiveFlags flags) const;
 
     Config(const Config &) = delete;
     Config& operator= (const Config &) = delete;

include/OpenColorIO/OpenColorTypes.h

@@ -774,6 +774,15 @@ extern OCIOEXPORT const char * OCIO_INACTIVE_COLORSPACES_ENVVAR;
  */
 extern OCIOEXPORT const char * OCIO_OPTIMIZATION_FLAGS_ENVVAR;
 
+/**
+ * The envvar 'OCIO_OPTIMIZATION_FLAGS' provides a way to force a given
+ * optimization level. Remove the variable or set the value to empty to
+ * not use it. Set the value of the variable to the desired optimization
+ * level as either an integer or hexadecimal value.
+ * Ex: OCIO_OPTIMIZATION_FLAGS="1" or "0x01" for ARCHIVE_FLAGS_MINIMAL.
+ */
+extern OCIOEXPORT const char * OCIO_ARCHIVE_FLAGS_ENVVAR;
+
 /**
  * The envvar 'OCIO_USER_CATEGORIES' allows the end-user to filter color spaces shown by
  * applications.  Only color spaces that include at least one of the supplied categories will be
@@ -955,6 +964,28 @@ extern OCIOEXPORT const char * OCIO_CONFIG_DEFAULT_NAME;
 extern OCIOEXPORT const char * OCIO_CONFIG_DEFAULT_FILE_EXT;
 extern OCIOEXPORT const char * OCIO_CONFIG_ARCHIVE_FILE_EXT;
 
+//!cpp:type:: Enum to control the behavior of archiving a :cpp:class:`Config`.
+//
+// TODO: extend docs
+// TODO: Python bindings
+// TODO: environment variable?
+//
+enum ArchiveFlags : unsigned long
+{
+    ARCHIVE_FLAGS_NONE                   = 0x0000,
+
+    ARCHIVE_FLAGS_FAST_COMPRESSION       = 0x02, // Compression level
+    ARCHIVE_FLAGS_NORMAL_COMPRESSION     = 0x06, // Compression level
+    ARCHIVE_FLAGS_BEST_COMPRESSION       = 0x09, // Compression level
+    ARCHIVE_FLAGS_COMPRESSION_MASK       = 0x0F, // Compression level mask
+
+    ARCHIVE_FLAGS_MINIMAL                = 0x0100, // Generate a Minimal Archive
+
+    ARCHIVE_FLAGS_DEFAULT = (ARCHIVE_FLAGS_NONE | ARCHIVE_FLAGS_BEST_COMPRESSION),
+
+    ARCHIVE_FLAGS_SAFEST = (ARCHIVE_FLAGS_NONE | ARCHIVE_FLAGS_BEST_COMPRESSION) // TODO: name is poor
+};
+
 // Built-in config feature
 // URI Prefix
 extern OCIOEXPORT const char * OCIO_BUILTIN_URI_PREFIX;

src/OpenColorIO/Config.cpp

@@ -49,6 +49,7 @@ const char * OCIO_ACTIVE_DISPLAYS_ENVVAR      = "OCIO_ACTIVE_DISPLAYS";
 const char * OCIO_ACTIVE_VIEWS_ENVVAR         = "OCIO_ACTIVE_VIEWS";
 const char * OCIO_INACTIVE_COLORSPACES_ENVVAR = "OCIO_INACTIVE_COLORSPACES";
 const char * OCIO_OPTIMIZATION_FLAGS_ENVVAR   = "OCIO_OPTIMIZATION_FLAGS";
+const char * OCIO_ARCHIVE_FLAGS_ENVVAR        = "OCIO_ARCHIVE_FLAGS";
 const char * OCIO_USER_CATEGORIES_ENVVAR      = "OCIO_USER_CATEGORIES";
 
 // Default filename (with extension) of a config and archived config.
@@ -5559,7 +5560,7 @@ bool Config::isArchivable() const
                 // 2) Path may not start with double dot ".." (going above working directory).
                 pystring::startswith(normPath, "..") ||
                 // 3) A context variable may not be located at the start of the path.
-                (ContainsContextVariables(path) && 
+                (ContainsContextVariables(path) && //TODO: if we can resolve context, do so and validate path to file
                 (StringUtils::Find(path, "$") == 0 || 
                  StringUtils::Find(path, "%") == 0)))
         {
@@ -5605,10 +5606,10 @@ bool Config::isArchivable() const
     return true;
 }
 
-void Config::archive(std::ostream & ostream) const
+void Config::archive(std::ostream & ostream, ArchiveFlags flags) const
 {
     // Using utility functions in OCIOZArchive.cpp.
-    archiveConfig(ostream, *this, getCurrentContext()->getWorkingDir());
+    archiveConfig(ostream, *this, getCurrentContext()->getWorkingDir(), flags);
 }
 
 } // namespace OCIO_NAMESPACE

src/OpenColorIO/OCIOZArchive.cpp

@@ -202,15 +202,28 @@ void addSupportedFiles(void * archiver, const char * path, const char * configWo
 }
 //////////////////////////////////////////////////////////////////////////////////////
 
-void archiveConfig(std::ostream & ostream, const Config & config, const char * configWorkingDirectory)
+ArchiveFlags EnvironmentOverride(ArchiveFlags oFlags) // TODO: test override
+{
+    const std::string envFlag = GetEnvVariable(OCIO_ARCHIVE_FLAGS_ENVVAR);
+    if (!envFlag.empty())
+    {
+        // Use 0 to allow base to be determined by the format.
+        oFlags = static_cast<ArchiveFlags>(std::stoul(envFlag, nullptr, 0));
+    }
+    return oFlags;
+}
+
+void archiveConfig(std::ostream & ostream, const Config & config, const char * configWorkingDirectory, ArchiveFlags flags)
 {
     void * archiver = nullptr;
     void *write_mem_stream = NULL;
     const uint8_t *buffer_ptr = NULL;
     int32_t buffer_size = 0;
     mz_zip_file file_info;
 
-    if (!config.isArchivable())
+    flags = EnvironmentOverride(flags);
+
+    if (!config.isArchivable()) // TODO: pass in flags?
     {
         std::ostringstream os;
         os << "Config is not archivable.";
@@ -238,8 +251,10 @@ void archiveConfig(std::ostream & ostream, const Config & config, const char * c
     ArchiveOptions options;
     // Make sure that the compression method is set to DEFLATE.
     options.compress_method = ArchiveCompressionMethods::DEFLATE;
-    // Make sure that the compression level is set to BEST.
-    options.compress_level  = ArchiveCompressionLevels::BEST;
+    // Default compression level is set to BEST.
+    options.compress_level  = flags & ARCHIVE_FLAGS_COMPRESSION_MASK
+                              ? ArchiveCompressionLevels(flags & ARCHIVE_FLAGS_COMPRESSION_MASK)
+                              : ArchiveCompressionLevels::BEST;
 
     // Create the writer handle.
 #if MZ_VERSION_BUILD >= 040000
@@ -305,7 +320,10 @@ void archiveConfig(std::ostream & ostream, const Config & config, const char * c
         ///////////////////////
         // Add all supported files to in-memory zip from any directories under working directory. 
         // (recursive)
-        addSupportedFiles(archiver, configWorkingDirectory, configWorkingDirectory);
+        if (HasFlag(flags, ARCHIVE_FLAGS_MINIMAL))
+            addSupportedFiles(archiver, configWorkingDirectory, configWorkingDirectory);
+        else
+            addSupportedFiles(archiver, configWorkingDirectory, configWorkingDirectory);
 
         // Close in-memory zip.
         mz_zip_writer_close(archiver);

src/OpenColorIO/OCIOZArchive.h

@@ -23,11 +23,13 @@ namespace OCIO_NAMESPACE
  * \param ostream Output stream to write the data into.
  * \param config Config object.
  * \param configWorkingDirectory Working directory of the current config.
+ * \param flags Archive flags used to .
  */
 void archiveConfig(
     std::ostream & ostream, 
     const Config & config, 
-    const char * configWorkingDirectory);
+    const char * configWorkingDirectory,
+    ArchiveFlags flags);
 
 /**
  * \brief Get the content of a file inside an OCIOZ archive as a buffer. 
@@ -106,6 +108,11 @@ class CIOPOciozArchive : public ConfigIOProxy
     std::map<std::string, std::string> m_entries;
 };
 
+// TODO: This "duplicates" flags function from Op.h could be a template?
+inline bool HasFlag(ArchiveFlags flags, ArchiveFlags queryFlag)
+{
+    return (flags & queryFlag) == queryFlag;
+}
 } // namespace OCIO_NAMESPACE
 
 #endif

src/apps/ocioarchive/main.cpp

@@ -45,6 +45,7 @@ int main(int argc, const char **argv)
     // Default value is current directory.
     std::string extractDestination;
 
+    bool minimal    = false;
     bool extract    = false;
     bool list       = false;
     bool help       = false;
@@ -61,6 +62,9 @@ int main(int argc, const char **argv)
                "    ocioarchive myarchive\n\n"
                "    # Archive myconfig/config.ocio into myarchive.ocioz\n"
                "    ocioarchive myarchive --iconfig myconfig/config.ocio\n\n"
+               "    # Archive from the OCIO environment variable into myarchive.ocioz\n"
+               "    #   requires all environment variables to be resolvable\n"
+               "    ocioarchive myarchive --minimal\n\n"
                "    # Extract myarchive.ocioz into new directory named myarchive\n"
                "    ocioarchive --extract myarchive.ocioz\n\n"
                "    # Extract myarchive.ocioz into new directory named ocio_config\n"
@@ -70,6 +74,7 @@ int main(int argc, const char **argv)
                "%*", parse_end_args, "",
                "<SEPARATOR>", "Options:",
                "--iconfig %s",  &configFilename,        "Config to archive (takes precedence over $OCIO)",
+               "--minimal",     &minimal,               "Create a minimal archive",
                "--extract",     &extract,               "Extract an OCIOZ config archive",
                "--dir %s",      &extractDestination,    "Path where to extract the files (folders are created if missing)",
                "--list",        &list,                  "List the files inside an archive without extracting it",
@@ -156,7 +161,11 @@ int main(int argc, const char **argv)
                 std::ofstream ofstream(archiveName, std::ofstream::out | std::ofstream::binary);
                 if (ofstream.good())
                 {
-                    config->archive(ofstream);
+                    OCIO::ArchiveFlags flags = OCIO::ARCHIVE_FLAGS_DEFAULT;
+                    if (minimal)
+                      flags = OCIO::ArchiveFlags(flags | OCIO::ARCHIVE_FLAGS_MINIMAL);
+
+                    config->archive(ofstream, flags);
                     ofstream.close();
                 }
                 else

src/apps/ocioview/ocioview/setup.py

@@ -47,6 +47,7 @@ def setup_env() -> None:
         ocio.OCIO_INACTIVE_COLORSPACES_ENVVAR,
         ocio.OCIO_OPTIMIZATION_FLAGS_ENVVAR,
         ocio.OCIO_USER_CATEGORIES_ENVVAR,
+        ocio.OCIO_ARCHIVE_FLAGS_ENVVAR,
     ):
         if env_var in os.environ:
             del os.environ[env_var]

src/bindings/python/PyConfig.cpp

@@ -894,7 +894,7 @@ void bindPyConfig(py::module & m)
         .def("archive", [](ConfigRcPtr & self, const char * filepath) 
             {
                 std::ofstream f(filepath, std::ofstream::out | std::ofstream::binary);
-                self->archive(f);
+                self->archive(f, ARCHIVE_FLAGS_DEFAULT); // TODO: pass flags in rather than default
                 f.close(); 
             }, 
             DOC(Config, archive))

src/bindings/python/PyTypes.cpp

@@ -865,6 +865,7 @@ void bindPyTypes(py::module & m)
     m.attr("OCIO_ACTIVE_VIEWS_ENVVAR") = OCIO_ACTIVE_VIEWS_ENVVAR;
     m.attr("OCIO_INACTIVE_COLORSPACES_ENVVAR") = OCIO_INACTIVE_COLORSPACES_ENVVAR;
     m.attr("OCIO_OPTIMIZATION_FLAGS_ENVVAR") = OCIO_OPTIMIZATION_FLAGS_ENVVAR;
+    m.attr("OCIO_ARCHIVE_FLAGS_ENVVAR") = OCIO_ARCHIVE_FLAGS_ENVVAR;
     m.attr("OCIO_USER_CATEGORIES_ENVVAR") = OCIO_USER_CATEGORIES_ENVVAR;
 
     // Roles