Vector Mask support

[reddesignsguy]

Hi Emil,

I'd like to contribute by supporting vector masks. What sections of the code do you think I should look at? And are there any gotchas I should know?

Here's some info I gathered:

• Vector masks are stored in Additional Layer Information and are indictated via the vmsk key
• /src/util/Enum.h currently lists the vmsk key but is unsupported
• TaggedBlock corresponds to blocks in the Additional Layer Information -- Seems like this will be the main component of implementing this task
• Path Resource Format is used to define the actual path information, however, this can be used in 2 different sections: Additional Layer Information for per-layer vector masks and Image Resources for document-wide working/saved paths.. will probably need to keep future-proofing in mind

[EmilDohne]

Hey @reddesignsguy, I appreciate you being interested in improving the PhotoshopAPI! Vector masks has been something on the (mental) backlog for a long time so I'm happy to see someone tackle it.

Gotchas/starting information

I'll start with the gotchas/starting information and go from there. I think the main thing to be aware of when working with the PhotoshopAPI is that it follows 2-step parsing.

1: The Photoshop file is first parsed pretty much verbatim into the PhotoshopFile struct which tackles decoding, decompression, tackling photoshops weird quirks etc.

2: This PhotoshopFile struct is then parsed into a LayeredFile<T> struct which is the user-facing API.

This is probably the main thing to keep in mind when you are writing the parsers for the layer masks. You will both need to implement the parser for the vector mask tagged blocks (as well as modifying anything on the LayerInfo struct to accomodate these changes if necessary), and the user-facing interface for dealing with vector masks that is a bit abstracted away from what photoshop does under the hood.

Entry points for your code

Here I'll give some links to the main entry points in the code to look at, but I would highly encourage taking one of the examples in the repo and stepping through the reading of a file with a debugger to get a feel for the flow

Tagged Blocks

To add a new tagged blocks there's two things you need to do. You will need to implement a parser for the VectorMaskTaggedBlock similar to this one:

https://github.com/EmilDohne/PhotoshopAPI/blob/master/PhotoshopAPI/src/Core/TaggedBlocks/PlacedLayerTaggedBlock.h

Once you have done so you'll need to add it to this file to actually have it read out as the PhotoshopFile parses:

https://github.com/EmilDohne/PhotoshopAPI/blob/master/PhotoshopAPI/src/Core/TaggedBlocks/TaggedBlockStorage.cpp

Registering with the layer

Once the tagged block is there, you will need to parse it from the PhotoshopFile -> LayeredFile as handled by this constructor:

https://github.com/EmilDohne/PhotoshopAPI/blob/master/PhotoshopAPI/src/LayeredFile/LayerTypes/Layer.h#L204

You'll likely need to modify the MaskMixin to support vector masks

https://github.com/EmilDohne/PhotoshopAPI/blob/master/PhotoshopAPI/src/LayeredFile/LayerTypes/MaskDataMixin.h

Roundtripping

To then roundtrip back for write, you'll need to modify this function here to generate the tagged blocks for the mask data.

https://github.com/EmilDohne/PhotoshopAPI/blob/master/PhotoshopAPI/src/LayeredFile/LayerTypes/Layer.h#L443

Note

You may need to do this for all derived layers (SmartObjectLayer, GroupLayer, ImageLayer) as that code is not too clean at the moment.

Resources and Tooling

Your main resource will likely be these two:

• The official photoshop file format reference https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/
  • Use this only as a guideline. Treat this document as a draft that some intern at adobe once made and was since abandoned. It will lie to you, it will abuse you, do not trust it.
• The amazing psd-tools repository, this already has support for parsing vector masks (but doesn't abstract it away much) https://github.com/psd-tools/psd-tools/blob/main/src/psd_tools/psd/vector.py . This is most likely to be correct

As for tooling to actually read the binary structure visually, I developed this some eons ago when I initially started working on the PhotoshopAPI. It is a parser for a vscode plugin that allows you to inspect the structure of the file by expanding/collapsing sections. This isn't a full parser by any means but will organize the file a bit better than just looking over the binary file

https://github.com/EmilDohne/PhotoshopFileInspector/

Closing remarks

As a final note to you, the PhotoshopAPI is by no means perfect and I initially started it when I was not very experienced with C++. I have since gotten better but a fair bit of the codebase still does some questionable things. As I add features I usually also try to cleanup wherever possible but if you see something weird it may not always be on purpose.

Godspeed! Let me know if there is any additional questions/guidance you need :)

[reddesignsguy]

Thank you!!

Could I get permission to push?

[EmilDohne]

No worries! For pushing you can just create a branch in your fork and then create a merge request to the main repo