GroupLayer Structure#

Equivalent of Photoshops Group Layer, has near-identical methods as the LayeredFile for modifying the hierarchy of the file.

template<typename T> struct GroupLayer : public Layer<T>#

Represents a group of layers that may contain nested child layers.

Template Parameters:: T – The data type for pixel values in layers (e.g., uint8_t, uint16_t, float32_t).

Masks

inline bool has_mask() const noexcept#

Checks whether the layer has a pixel mask.

Returns:: true if a mask is present, otherwise false.

inline std::vector<T> get_mask() const#

Retrieves the mask channel data, if present.

If the layer does not have a mask, this function returns an empty vector.

The returned vector contains

mask_width() * mask_height() elements.

inline void get_mask(std::span<T> buffer) const#

Fills a preallocated buffer with the mask channel data, if present.

If no mask is present, the buffer remains unchanged.

Parameters:: buffer – A preallocated buffer expected to have exactly mask_width() * mask_height() elements.

inline compressed::channel<T> extract_mask()#

Extract the compressed mask channel used internally.

Throws:: std::runtime_error – if no mask is present (as checked by has_mask).

inline void set_mask(std::span<const T> buffer, size_t width, size_t height)#

Sets the layer’s mask to the given buffer.

If no mask was previously held the inserted mask will be at the top-left of the canvas. Use mask_position to adjust this.

Parameters:

buffer – The image data for the mask, provided in scanline order.
width – The width of the new mask.
height – The height of the new mask.

Throws:

std::invalid_argument – If the buffer size does not match the expected dimensions.

inline void set_mask(compressed::channel<T> channel)#

inline void set_mask(const LayeredFile<T> &document, std::span<const T> buffer, std::optional<size_t> width = std::nullopt, std::optional<size_t> height = std::nullopt)#

Sets the layer’s mask to the given buffer.

If the layer previously had a mask, the new mask will be centered at the same position.

If no mask was previously present, the new mask will be centered on the document.

Parameters:

document – The file to which this mask layer belongs.
buffer – The image data for the mask, provided in scanline order. If width and height are unspecified, the buffer must have exactly mask_width() * mask_height() elements. If no dimensions are specified and the layer previously had no mask, an exception is thrown.
width – (Optional) The width of the new mask. Required if replacing with a differently sized mask.
height – (Optional) The height of the new mask. Required if replacing with a differently sized mask.

Throws:

std::invalid_argument – If the buffer size does not match the expected dimensions.
std::runtime_error – If no mask existed and no explicit dimensions were provided.

inline void set_mask_compression(Enum::Compression _compcode) noexcept#

Set the masks write compression.

If has_mask() evaluates to false this is a no-op.

Parameters:: _compcode – The compression codec to apply on-write.

inline Geometry::BoundingBox<double> mask_bbox() const#

Retrieves the bounding box of the mask, if present.

If no mask exists, this function returns a zero-sized bounding box.

Returns:: The mask’s bounding box, or an empty bounding box if no mask is present.

inline size_t mask_width() const#

Retrieves the width of the mask, if present.

If no mask exists, this function returns zero

Returns:: The mask’s width or zero if no mask exists

inline size_t mask_height() const#

Retrieves the height of the mask, if present.

If no mask exists, this function returns zero

Returns:: The mask’s height or zero if no mask exists

inline Geometry::Point2D<double> mask_position() const#

Retrieves the position of the mask, defined as its center.

If no mask is present, this function returns {-1.0, -1.0}.

Returns:: The center position of the mask, or {-1.0, -1.0} if no mask exists.

inline void mask_position(Geometry::Point2D<double> position)#

Sets the center position of the mask.

If no mask is present, this function does nothing.

Parameters:: position – The new center position of the mask.

inline bool mask_relative_to_layer()#

Checks whether the mask is relative to the layer.

Returns:: true if the mask is relative to the layer, otherwise false.

inline void mask_relative_to_layer(bool value)#

Sets whether the mask should be relative to the layer.

Parameters:: value – true to make the mask relative to the layer, otherwise false.

inline bool mask_disabled()#

Checks whether the mask is disabled.

Returns:: true if the mask is disabled, otherwise false.

inline void mask_disabled(bool value)#

Enables or disables the mask.

Parameters:: value – true to disable the mask, otherwise false.

inline uint8_t mask_default_color()#

Retrieves the mask’s default fill color.

Returns:: The default mask color.

inline void mask_default_color(uint8_t value)#

Sets the mask’s default fill color.

Parameters:: value – The new default color value.

inline std::optional<uint8_t> mask_density()#

Retrieves the mask density, if specified.

Returns:: The mask density value, or an empty optional if unspecified.

inline void mask_density(uint8_t value)#

Sets the mask density.

Parameters:: value – The new mask density.

inline void mask_density(std::optional<uint8_t> value)#

Sets the mask density, allowing for removal.

Parameters:: value – An optional new mask density.

inline std::optional<float64_t> mask_feather()#

Retrieves the mask feathering amount, if specified.

Returns:: The mask feather value, or an empty optional if unspecified.

inline void mask_feather(float64_t value)#

Sets the mask feathering amount.

Parameters:: value – The new mask feather value.

inline void mask_feather(std::optional<float64_t> value)#

Public Types

using value_type = T #: Template type accessor which can be used using decltype(layer::value_type)

using channel_type = std::unique_ptr<channel_wrapper>#

Public Functions

inline std::vector<std::shared_ptr<Layer<T>>> &layers() noexcept#

inline const std::vector<std::shared_ptr<Layer<T>>> &layers() const noexcept#

inline void layers(std::vector<std::shared_ptr<Layer<T>>> layer_vec) noexcept#

inline bool &collapsed() noexcept#

inline bool collapsed() const noexcept#

inline void collapsed(bool is_collapsed) noexcept#

inline GroupLayer(Layer<T>::Params &parameters, bool isCollapsed = false)#

Constructs a GroupLayer with the given layer parameters and collapse state.

Parameters:

parameters – The parameters for the group layer.
isCollapsed – Specifies whether the group layer is initially collapsed.

inline void add_layer(const LayeredFile<T> &layeredFile, std::shared_ptr<Layer<T>> layer)#

Adds a layer to the group, checking for duplicates in the process.

Parameters:

layeredFile – The layered file containing the group.
layer – The layer to be added.

inline void remove_layer(const int index)#

Removes a layer at the given index from the group.

Parameters:: index – The index of the layer to be removed.

inline void remove_layer(std::shared_ptr<Layer<T>> &layer)#

Removes the specified layer from the group.

Parameters:: layer – The layer to be removed.

inline void remove_layer(const std::string layerName)#

Removes the specified layer from the group.

Parameters:: layerName – The name of the layer to be removed

inline virtual std::tuple<LayerRecord, ChannelImageData> to_photoshop() override#

Converts the group layer to Photoshop layerRecords and imageData.

This is part of the internal API and as a user you will likely never have to use this function

Returns:: A tuple containing layerRecords and imageData.

inline GroupLayer(const LayerRecord &layerRecord, ChannelImageData &channelImageData, const FileHeader &header)#

Constructs a GroupLayer using layerRecord, channelImageData, and file header.

This is part of the internal API and as a user you will likely never have to use this function

Parameters:

layerRecord – The layer record for the group layer.
channelImageData – The channel image data for the group layer.
header – The file header for the group layer.

inline const std::string &name() const noexcept#: The layers’ name. Stored as a utf-8 string.

inline std::string &name() noexcept#: The layers’ name. Stored as a utf-8 string.

inline void name(const std::string &layer_name) noexcept#: The layers’ name. Stored as a utf-8 string.

inline Enum::BlendMode &blendmode() noexcept#: The blendmode of the layer, the Passthrough blendmode is only valid for groups.

inline Enum::BlendMode blendmode() const noexcept#: The blendmode of the layer, the Passthrough blendmode is only valid for groups.

inline void blendmode(Enum::BlendMode blend_mode) noexcept#: The blendmode of the layer, the Passthrough blendmode is only valid for groups.

inline bool &locked() noexcept#: Whether the layers’ pixel values are locked. This is currently an all or nothing setting.

inline bool locked() const noexcept#: Whether the layers’ pixel values are locked. This is currently an all or nothing setting.

inline void locked(bool is_locked) noexcept#: Whether the layers’ pixel values are locked. This is currently an all or nothing setting.

inline bool &visible() noexcept#: Visibility toggle of the layer.

inline bool visible() const noexcept#: Visibility toggle of the layer.

inline void visible(bool is_visible) noexcept#: Visibility toggle of the layer.

inline bool &clipping_mask() noexcept#: Clipping mask toggle of the layer, clips it to the layer below.

inline bool clipping_mask() const noexcept#: Clipping mask toggle of the layer, clips it to the layer below.

inline void clipping_mask(bool is_clipped) noexcept#: Clipping mask toggle of the layer, clips it to the layer below.

inline float opacity() const noexcept#

The layers’ opacity.

In photoshop this is stored as a uint8_t from 0-255 but access and write is in terms of a float for better consistency.

inline void opacity(float value) noexcept#

The layers’ opacity.

In photoshop this is stored as a uint8_t from 0-255 but access and write is in terms of a float for better consistency.

inline virtual uint32_t width() const noexcept#: The layers’ width from 0 - 300,000.

inline virtual void width(uint32_t layer_width)#: The layers’ width from 0 - 300,000.

inline virtual uint32_t height() const noexcept#: The layers’ height from 0 - 300,000.

inline virtual void height(uint32_t layer_height)#: The layers’ height from 0 - 300,000.

inline virtual float center_x() const noexcept#

The layers’ x center coordinate

I.e. if the layer has the bounds { 200, 200 } - { 1000, 1000 } The center would be at { 600, 600 }

inline virtual void center_x(float x_coord) noexcept#

inline virtual float center_y() const noexcept#

The layers’ y center coordinate

I.e. if the layer has the bounds { 200, 200 } - { 1000, 1000 } The center would be at { 600, 600 }

inline virtual void center_y(float y_coord) noexcept#

inline float top_left_x() const noexcept#: Convenience function for accessing the top left x coordinate of a layer.

inline float top_left_y() const noexcept#: Convenience function for accessing the top left y coordinate of a layer.

inline Enum::ColorMode color_mode() const noexcept#: The color mode with which the file was created, only stored to allow better detection during channel access for e.g. image layers

inline virtual void set_write_compression(Enum::Compression _compcode)#

Set the write compression for all channels.

This has no effect on the in-memory compression of these channels but only on write. Setting this therefore has a near-zero runtime cost.

Parameters:: _compcode – The new compression setting.

Public Static Attributes

static constexpr auto s_mask_index = Enum::ChannelIDInfo{Enum::ChannelID::UserSuppliedLayerMask, -2}#: Colormode independent mask index as Enum::ChannelIDInfo that may be used.