Future API additions

[qyot27]

To make it easier to keep track of things we might want to add in the future and have a checklist of things to add or change before another API bump occurs, this would help. Suggestions are welcome, this is a brainstorming thread after all.

chroma location:
https://forum.doom9.org/showthread.php?p=1933602#post1933602
It seems to already be defined here, but it looks like there's nothing corresponding to it in avisynth_c.h. I don't know if that's what the PlanarChromaAlignment stuff in avisynth.cpp is intended to expose or not.

endianness:
Since it's now possible to build and use AviSynth+ on PowerPC, which is traditionally big endian (ppc/ppc32 and ppc64 are big endian, ppc64le/el on POWER8 and above is a little endian mode), one problem I ended up encountering is that while video was okay being interpreted by FFmpeg, audio was not, and I needed to explicitly tell FFmpeg it was handling big endian audio output from AviSynth+. The result is a somewhat kludgy if/else block in FFmpeg's libavformat/avisynth.c that checks for big endian and redefines a macro that I substitute for the audio format later on.

It would be nicer if we had an API check, avs_is_big_endian/little_endian, and a corresponding set of audio (and maybe video, if we find that other apps may need that) stubs that explicitly declare themselves as big endian. That way it could be handled without redefining anything in the client programs, or requiring the clients to re-implement endianness checks themselves. This could also assist in the case of other big endian architectures that could be added in the future (SPARC is on a to-do list, if I'm able to get QEMU to play nice).

And for reviving a really big idea,

direct frame copy:
Way back in the early history of AviSynth, there were a couple of attempts to create a fork that was capable of doing Direct Stream Copy operations. It was called DSynth. There's only one or two references to it in the AviSynth docs at all, including musing that it would be part of the v3 effort:
http://avisynth.nl/index.php?title=Special%3ASearch&search=dsynth&go=Go
https://forum.doom9.org/showthread.php?t=71482

With us now supporting settable frame properties, would it actually be possible to do something substantive with DSynth now, just not as a separate fork? Dedicated Trim and Splice options would be necessary (DTrim, D(Un)alignedSplice), as well as some way for source filters to react to their use and pass frames or GOPs through without decoding to raw (frameprop data?). It would also require client programs be able to see the flagging in order to handle it as a DSC operation, and AviSynth+ to do actual output of the undecoded frames, as well as maybe another function that could override DTrim/Splice and force them back into regular Trim and Splice operations when a client can't accept the undecoded output or segmented stream (if we're somehow able to have output as decoded and undecoded mixed).

[pinterf]

Thoughts on chroma placement (just thinking):

Chroma placement constants are defined in avisynth.h but are used nowhere else.
The constants occupy three bits which can theoretically be stuffed into the video format descriptor field (pixel_type: 20-22 bits).

Note that we have another "property"-like field in VideoInfo is "int image_type" which is bit-mapped field. 3 bits of 32 are used now, which hold interlacing-related IT_BFF, IT_TFF or IT_FIELDBASED clip properties.

While the IT_ fields have direct read/write (https://github.com/AviSynth/AviSynthPlus/blob/master/avs_core/core/interface.cpp#L126) and check (https://github.com/AviSynth/AviSynthPlus/blob/master/avs_core/core/interface.cpp#L105) methods in VideoInfo, chroma placement lacks them.

See
http://avisynth.nl/index.php/Clip_properties#Video:_Interlacing
http://avisynth.nl/index.php/Filter_SDK/Cplusplus_API/VideoInfo

in Avisynth.h:

// Imagetype properties

int image_type;

 enum {
   IT_BFF = 1<<0,
   IT_TFF = 1<<1,
   IT_FIELDBASED = 1<<2
 };

 // Chroma placement bits 20 -> 23  ::FIXME:: Really want a Class to support this
 enum {
   CS_UNKNOWN_CHROMA_PLACEMENT = 0 << 20,
   CS_MPEG1_CHROMA_PLACEMENT   = 1 << 20,
   CS_MPEG2_CHROMA_PLACEMENT   = 2 << 20,
   CS_YUY2_CHROMA_PLACEMENT    = 3 << 20,
   CS_TOPLEFT_CHROMA_PLACEMENT = 4 << 20
 };

As you said, none of these chroma placement constants appear in avisynth_c.h
As the comment says: "::FIXME:: Really want a Class to support this" so we do not have "nice" methods to access them.
If ever they would be used, I removed it from pixel_type struct and move them into image_type.

Frame properties.

Using them seems to be a better approach for me than forcing further properties in a 32 bit VideoInfo pixel_type field.
There are a couple more properties that are as important as the chroma placement.
http://avisynth.nl/index.php/Internal_functions#Reserved_frame_property_names

They would even store the IT_xxx clip properties as frame properties: the three bits in VideoInfo::image_type is similar to the frame properties _FieldBased and _Field. Obviously these properties we are talking about are usually constant for the lifetime of the clip.

Note that clip properties (fixed in VideoInfo struct) and frame properties (could be different for each frame) are logically different.

[pinterf]

Another idea: 64 bit integer and "double" type in AVSValue. Yes I know, only on 64 bit OS.
We are in 2021. I guess most installations use 64 bit versions now which can benefit from it.

[pinterf]

Idea: GetInterfaceVersion: query the interface version directly. Anything is better than the present method when avisynth is throwing an exception when a too advance interface version is expected.

[qyot27]

Isn't that what GetVersion/avs_get_version already does? FFmpeg uses it in virtually the exact way you're talking about, by checking to see if the interface version is correct, and gracefully exiting with a 'you need to upgrade' message if it's too old.

[pinterf]

It checks against the clip and not the host avisynth core interface version which is not the same thing.

[pinterf]

When a plugin is written, it is using the actual avisynth header, even an earlier version.
In filter definition the actually created Clip will inherit class GenericVideoFilter : public IClip.
IClip has virtual int __stdcall GetVersion() { return AVISYNTH_INTERFACE_VERSION; }
which is using the AVISYNTH_INTERFACE_VERSION e.g. 3, 5, 6 or 8 of the actually used avisynth.h. GetVersion is rarely overridden by plugin writers when creating the VideoFilter class. So the actual GetVersion will return the avisynth header version at the time when the plugin was written.

There are a couple of checks in Avisynth code: clip->GetVersion() >= 5 which is basically checking the avisynth header version of child filter.

What I was mentioning the env->CheckVersion method which can be used right after creating script environment.

On the other hand, in FFmpeg case the latest clip will probably come from cache which is an internal filter of Avisynth core and the clip will report the core's version number. I wonder what is reported to FFmpeg when the latest filter is a DONT_CACHE_ME filter which was built with a AVISYNTH_INTERFACE_VERSION = 5 header. Rare case though.

EDIT:
"When using the raw IClip interface it is the authors responsibility to declare the level of support the plugin provides."
https://github.com/AviSynth/AviSynthPlus/blob/master/distrib/FilterSDK/AviSynthInterfaceVersion.htm#L53

[pinterf]

With the latest additions - not the new EnvProperty constants, but my additions of MakePropertyWritable and IsPropertyWritable - I don't know if we need to step the main version from 8 to 9. Having a bugfix version step seems to be enough.
Originally I'd like to have a step to 9 but developer folks are lazy and will use the header which contains an explicite AVISYNTH_INTERFACE_VERSION 9 and include it automatically in CheckVersion(AVISYNTH_INTERFACE_VERSION) which will automatically result in an incompatibilty with previous avs versions.

O.K., I know this is a bad habit to include there the constant from the actual avisynth header. But I remember when I had to fix a wrapper for megui, they excluded avisynth interface 6 in the very same way.

When we'd only change the stepping (which is already done) and the main version is kept to be 8, we'd postpone support and explain such cases.

Btw: I noticed (again, not priority) that almost all the files contain Avisynth 2.5 info at the top. Isn't it due time to update it to Avisynth+ project? (and I don't know the licence text is still valid or not)

[qyot27]

Additions like MakePropertyWritable/IsPropertyWritable, as actual newly-introduced API functions, would require bumping to version 9. The bugfix version would be for things not as tied to the API but still important for compatibility - like how the C interface couldn't properly read out frame properties even though the functions were there. Or for newly added user-facing filters that aren't on the developer side; let's say we add a FishEye() filter, and some time later a Timeline() filter - if bugfix was bumped each time, it would be possible for a program needing to know which of those user functions could be Invoke()'d to figure it out by checking the bugfix version against however we would document the bugfix version changes.

A combination of the two might also happen in the circumstance that something like how you mentioned adding more formats like double or int64 to AVSValue (or why not go nuts, even quad* or octuple**). The addition of them into AVSValue might (?) require bumping the interface version because it would affect compatibility, but extending existing filters to act on them in special situations or adding new ones would be able to get away with only bumping bugfix.

*not really that nuts, since POWER9, AArch64, and RISC-V all have defined support for quad float and varying levels of hardware support. It was also defined in SPARC v8 and v9 but the only other reference there just mentions that it hadn't shown up in hardware as of 2004.

**this document mirrored from Apple's developer site notes implementing oct-precision operations in AltiVec on a G4 back in 2002, and it being 4x faster than an equivalent C++ version. Not that I know what use oct-precision float would have in video processing, but maybe it's something it would grow into - give people the tool, and they'll figure out how to use it.

RE: copyright dates and versions, that's kind of a mess. And as IANAL, I'm not going to pretend I know anything about what we should do on that point aside from maybe just leaving it alone and only adding a mention of AviSynth+ if we've significantly altered that particular file (and of course this would be true of files that were introduced as part of AviSynth+ with no equivalent code path in 2.5/2.6). It would be nice to tidy it all up - recenter all the license stuff into a single file and standardize the source headers with appropriate dates and authors and reference to the license in a single style - but that is a bit daunting.

[pinterf]

Somehow in this commit: 70e54dd I succeeded to upload an avs_core/avisynth_conf.h
What is this and does it do any harm if it's there? Did I have it accidentally? In this case it must be moved into .gitignore.

[qyot27]

avisynth_conf.h does indeed need to be in .gitignore and removed from the source tree. It's only supposed to be generated at configure time, as it controls the user-switchable plugin directory locations on non-Windows.

[pinterf]

@qyot27
When should we really change Avisynth version? Is there a best practice? Change it when the first mod after a release occurs or wait as long as possible?
I made the change in version.h.in to 3.7.3 only on my desktop but avoided to upload to the repo until a quasi-final 3.7.3 is available.

[qyot27]

I would usually go with 'when said release is imminent', but I also know it's potentially confusing to some users since the standard version number appears in Version() and such and so all those incremental builds between releases could still say '3.7.2' but not match the revision number of the actual 3.7.2. Or that it could say '3.7.3' but that version hasn't actually been officially released yet. Neither of those is all that great.

I think maybe a way to navigate this would be to have a substitute for the version number for builds that aren't official releases, and have it ifdeffed so that when we go to make the release, we just set that ifdef and the version number appears. Then the timing of the version number changing under the hood isn't as likely to get in the way or be confusing.

So let's say we hook the define into CMake with an option like -DENABLE_RELEASE_VERSION=ON. If used, it would show the standard style:
AviSynth+ 3.7.2 (rXXXX, branch, arch)

But leaving it turned off would show:
AviSynth+ version-next (rXXXX, branch, arch)
or maybe some variation of
AviSynth+ 3.7_version-next (rXXXX, branch, arch)
so it at least identifies the main version series it's a part of.

The point is that version-next or whatever the text happens to be makes it very clear that it's a development build.

Speaking of the bump to V10, shouldn't the new AVSValue::GetType have a C-interface equivalent? Or is that something very C++-ish that just doesn't make sense for the C-interface to have?

[pinterf]

Thanks for the explanation. I even though of an odd-even cycle, step to odd after the first change, step to even only for the final release.

Speaking of the bump to V10, shouldn't the new AVSValue::GetType have a C-interface equivalent? Or is that something very C++-ish that just doesn't make sense for the C-interface to have?

Intentional. C has direct access to AVS_Value. The avs_is_XXXX and avs_as_XXXX are just inline helper functions, no API exists for them.