Ownership of this repository was transfered to the newly created @cosmigo organization:

• https://github.com/tajmone/pmotion-assets (previous location)
• https://github.com/cosmigo/pmotion-assets (current location)

Replace all references to the old repository URL, form the @tajmone user account to the @cosmigo organization in:

• Repo settings comments.
• Markdown files.
• LICENSE file.
• AsciiDoc sources.
  • Rebuild HTML docs.

TRAVIS CI NOTE — Travis CI validation will not work until @cosmigo enables Travis on the repository (See cosmigo/pmotion2svg#1). Since the badge is already broken on master branch, there's no need to wait for Travis enabling before merging these fixes.

References

• GitHub Docs » Transferring a repository

I need a clarification about the plugin function getImageCount().

This function is documented as being able to return error, but it's the only function of those that can set error that is also expected to return a value (i.e. the number of frames).

I'm assuming that in case of error the function is also to return false (0), and that it's not enough to just set the error. I'm assuming that, since at least 1 image is expected by PM, a return value of 0 would be considered an error.

If this is the case, it might be worth mentioning it in the interface documentation, because it's not obvious.

Se also:

• cosmigo/pmotion-purebasic#5

• Group fonts in subfolders to reduce quantity of fonts per folder.
• Create fonts preview images.

Grouping fonts

There are too many fonts in the image-fonts/ and bmf-fonts/ directories. They should grouped in folders by the first letter of the font name. The problem is that many font files are just named as numbers.

For the BMF fonts, it should be possible to extract their name from the font metadata, with some dedicated tool.

Many image fonts from the Guldkrans’s collection were originally named with numbers, apparently, so I'll have to find another criteria to sort them in subfolders.

Fonts previews

I need to find (or create) a tool to automatically create an image preview of each BMF font, possibly using the font metadata to add its name to the image too, along with a specimen of the font characters, digits and symbols.

Missing info on DLL functions.

I need to understand if DLL functions specifically targeting import or export functionality can be left out entirely in those plug-ins that won't use them — i.e. if these functions still require defining DLLProcedures that do nothing, or if they can simply be omitted since PM wouldn't try to call them after having acknowledged the plug-in supported features via the registration functions.

For example, an import plug-in shouldn’t expect any calls to beginWrite() or
writeNextImage(), and an export plug-in shouldn’t expect any calls to getTransparentColor() or isAlphaEnabled().

For more info, see also:

• Cosmigo Forum » HELP: More File I/O Interface Clarifications
• cosmigo/pmotion-purebasic#2

Now that all batch scripts have been converted to Bash scripts it's possible to extend the build tests:

• Switch Ubuntu distro from trusty to xenial.
• Add Asciidoctor Build:
  • Clone and build Highlight from sources.
  • Install Asciidoctor (Ruby) and dependencies.
  • Run docs_src/build.sh in a separate job.
  • Update badge hovering info in README.adoc
• Add Sass Build:
  • Install Dart Sass.
  • Run _assets/sass/build.sh in a separate job.
  • Update badge hovering info in README.adoc

When Travis CI is correctly setup and working, and the build status badge is green again (See cosmigo/pmotion2svg#1):

• Check that there are no more links/URLs pointing to the old repository.
• Close the Cosmigo Transferal milestone.

References

• GitHub Docs » Transferring a repository

FAKE Plugin v0.0.9 | PMNG 7.2.0.7

@jan-cosmigo, the Fake plug-in is a proof-of-concept File I/O plug-in which fakes exporting images to the .fake format (doesn't actually save anything) as an excuse to log all the DLL calls that PMNG executes to the plug-in, both at initialization time as well as when exporting.

NOTE — You'll always find the pre-compiled DLL of the latest version on our shared GDrive folder, which is automatically deployed when I build the final DLL.

This plug-in has helped me get a better insight about how the File I/O interface actually works in real case scenarios, and provided me with the order in which DLL functions are called.

But it also shows some strange things, i.e. that PMNG seems to call some initialization functions more than once. I'm not sure why this happens, and whether it's caused by the fact that the plug-in causes a slight delay in its responses due to the visual logging, or whether that's the way the interface is supposed to work.

In any case, I though it was worth providing you with the latest logs, in case these redundant calls are not supposed to occur, and also because I'm curious about them since I've noticed that their occurrence is not fixed and might change depending on how many plug-ins are present in the plugins/ folder.

Initialization Log

Here's the full log from when the DLL is attached to PMNG's process up to the end of all initialization calls:

13:48:43 | initialize(*language, *version, *animation)
         | | *language  <--  'en'
         | | *version    --> 1
         | | *animation  --> 0
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | isReadSupported()
         | | --> false
13:48:43 | isWriteSupported()
         | | --> true
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileExtension()
         | | --> "fake"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileExtension()
         | | --> "fake"
13:48:43 | getFileExtension()
         | | --> "fake"
13:48:43 | getFileBoxDescription()
         | | --> "FAKE - PureBASIC"
13:48:43 | getFileExtension()
         | | --> "fake"
13:48:43 | getFileExtension()
         | | --> "fake"
13:48:43 | getFileExtension()
         | | --> "fake"
13:48:43 | isReadSupported()
         | | --> false
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:43 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:45 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:45 | isReadSupported()
         | | --> false
13:48:46 | getFileTypeId()
         | | --> "purebasic.fake"
13:48:46 | getFileTypeId()
         | | --> "purebasic.fake"

As you can see, getFileBoxDescription() is called multiple times (10 times!), and so is getFileTypeId() (29 times), as well as others (but not all).

I was wondering whether this has to do with the fact that PMNG has multiple File I/O interfaces (image import/export, animation import/export, palette import/export, and so on), which would explain why these are called multiple times — although it would make more sense to call them once and store the returned values, or memoize these calls to avoid redundancy (I've noticed that when there are more than 3 plugins PMNG startup can get quite slow).

Image Export Log

And here's the log from a simulated image export (Save Image As » "FAKE"):

13:55:04 | isReadSupported()
         | | --> false
13:55:04 | isReadSupported()
         | | --> false
13:55:10 | getFileTypeId()
         | | --> "purebasic.fake"
13:55:10 | getFileTypeId()
         | | --> "purebasic.fake"

... up to when I chose the "FAKE" format in the PMNG export dialog.
(again, you can see the duplicate calls)

And then, after having confirmed the "FAKE" format and the next PMNG's options pop-up dialog (pixel scale, effects, etc.):

13:56:06 | getFileExtension()
         | | --> "fake"
13:56:06 | getFileExtension()
         | | --> "fake"
13:56:06 | setFilename( $062037CC )
         | | *filename_pnt <-- "D:\test\KongTest.fake"
         | | FILE: KongTest.fake
13:56:06 | getFileTypeId()
         | | --> "purebasic.fake"
13:56:06 | setFilename( $062037CC )
         | | *filename_pnt <-- "D:\test\KongTest.fake"
         | | FILE: KongTest.fake
         | | (same as before)
13:56:06 | beginWrite()
13:56:06 | writeNextImage()
13:56:06 | finishProcessing()
13:56:06 | getFileTypeId()
         | | --> "purebasic.fake"

Of all these redundant calls, only the double call to setFilename() might actually affect plugin developers, depending on how the call is handled — as you can see from the second call in the above log, the FAKE plugin explicitly checks if the filename being passed is the same as the previous one, a check I introduced when noticing that the function might be called multiple times during a single image export operation.

The rest of the redundant calls are not really a concern to developers, since they are just plugin-info retrieval calls (which plugins should blindly obey to).

I was just curious on why all these redundant calls are there — especially since I'm planning to work an a File I/O simulator, to simplify testing plugins during development (i.e. not having to close and launch PMNG at every code edit, but just for final testing).

@jan-cosmigo, There seems to be a mistake in the loadNextImage() function in the original Developer Interface document, where the delayMs parameter is a variable in the Delphi function signature, but a pointer in the C++ function:

function loadNextImage( colorFrame,
                        colorFramePalette,
                        alphaFrame,
                        alphaFramePalette: Pointer;
                        var delayMs: word
): boolean; stdcall;

bool  __stdcall loadNextImage( unsigned char*  colorFrame,
                               unsigned char*  colorFramePalette,
                               unsigned char*  alphaFrame,
                               unsigned char*  alphaFramePalette,
                               unsigned short* delayMs
);

By looking at the C++ sources of the sample plugin from Cosmigo website, the correct one is the C++ function, where delayMs is a pointer (i.e. the plugin passes the value by writing its pointer).

• Developer Interface — at Cosmigo website.
• Developer Interface — in this repository website.

I can't fix it in the repository document unless it's fixed upstream, on the Cosmigo website, for the doc in this repo is meant to be a faithful copy of the original — i.e., unless it's OK with you (but then I should remove the statement regarding it being a faithful reproduction).

• When original document is fixed on Cosmigo website, fix it also in this repository.

@jan-cosmigo, please enable Discussions from the repository settings, which will allow us to engage in general discussion on PMNG related topics without cluttering Issues (which should be restricted to tracking practical tasks for the repository development).

The Discussions feature wasn't available at the time the repository was created, and I forgot to enable it. Now I don't have access to the Settings panel, so I have to ask you to enable it.

Thanks.

@jan-cosmigo, There seems to be a mistake in the description of the writeNextImage() function in the original Developer Interface document, which wrongly mentions the width and height parameters in the parameter table — which are not in the function signature, and shouldn't be there either.

• Developer Interface — at Cosmigo website.
• Developer Interface — in this repository website.

Probably these two parameters ended up in the table accidentally, due to copy and paste operations.

I can't fix it in the repository document unless it's fixed upstream, on the Cosmigo website, for the doc in this repo is meant to be a faithful copy of the original — i.e., unless it's OK with you (but then I should remove the statement regarding it being a faithful reproduction).

• When original document is fixed on Cosmigo website, fix it also in this repository.

Currently, whenever an image containing an Alpha layer is exported, the plugin is invoked twice (for image.ext and image.alpha.ext). This occurs regardless of whether isWriteTrueColorSupported() returns true or false.

This seems connected to PM NG native behaviour when saving to file formats that don't support alpha channels, for which PM created and additional .alpha.<ext> file to store the Alpha layer in order to reconstruct it when loading that image again.

This is either a bug or an undocumented feature — the former suggests that PM should be handling creation of the extra file.

For more details, see also:

• Cosmigo Forum » File I/O: Exporting image with Alpha layer creates two files
• cosmigo/pmotion-purebasic#4

• Try to understand how this bug affects the current interface.
  • Annotate the problem in the language agnostic interface.
• Track PMNG updates for when it's fixed.

Missing info on DDE plugins.

In his Pro Motion DDE Interface in C, Thiadmer Riemersma brings up the issue of wether asynchronous execution of DDE plugins is mandatory or not:

My implementation of a DDE “execute” is asynchronous. I do not know whether Pro Motion requires this. A few other applications for which I implemented DDE conversations required asynchronous execution, so I left it that way. Note that the Delphi implementation also does an asynchronous execution.

• Q: Can DDE plugins be interfaced synchronously too?
• Should I add a clarification footnote to the original document providing the answer for that? (I think Thiadmer won't mind this)

For more info, see also:

• cosmigo/pmotion-purebasic#3

Update CONTRIBUTING.md:

• EditorConfig:
  • Mention that the repository contains EditorConfig setting to help end users stick to the code styles conventions via editors that support the standard, as well as to enforce code styles via Travis CI validation.
  • Mention installing EClint and running the validate.sh script locally before committing and creating PRs.

Missing info on DLL functions.

Is the canExtractPalette() a generic DLL function gathering info about the plug-in supported features (e.g. like isReadSupported()) or does it apply to the specific files being processed? In other words, is it a plug-in registration function or is called on a per-file basis?

For more info, see also:

• Cosmigo Forum » HELP: More File I/O Interface Clarifications
• cosmigo/pmotion-purebasic#1