Information request: better release notes

[AaronL]

As a general rule, the release notes that pertain to the Intel Media SDK and QuickSync are either nonexistent, confusing, or in some cases incorrect.  Mostly, they are nonexistent.  Whenever a new version of the Intel Media SDK is released, a release notes file is included with the SDK.  Unfortunately, most of these release notes don't actually pertain to the SDK--they instead pertain to the Intel Graphics driver package, although it is impossible to tell which Intel Graphics driver packages they pertain to.  For example, here's a recent release note from the Intel Media SDK release notes file:  "HW Accelerated HEVC encode max macroblock per second report can work incorrectly for some particular driver versions."  Since the "particular driver versions" aren't mentioned, there is no way to know which driver version to use to address this particular issue, whatever this particular issue is describing.  In fact, there is no mention, anywhere in the latest Intel Media SDK (2016 R2) release notes, of a recommended driver version of the various different hardware platforms.  And, the driver version is of great significance when it comes to the Intel Media SDK because all of the actual Media SDK functionality, at least when it comes to using QuickSync for HW encoding/decoding/VPP/etc, comes from the driver package, not the SDK.

I mentioned that most release notes are nonexistent.  That's because every time that an Intel Graphics driver package is released, there is no mention of any changes that pertain to the Intel Media SDK and QuickSync in the release notes for the driver package, even when it is clear, from Media forum discussions, that relevant changes were made.  This is a problem of significance for Intel Media SDK developers, since there is no way to know if one should upgrade to a particular driver version in order to benefit from improvements relevant to QuickSync.  I understand that the Intel Graphics driver incorporates many different components, and the Media SDK is only one small part of them.  If the relevant group(s) at Intel cannot be convinced to include Media SDK-related release notes in the Intel Graphics driver package, then may I suggest that someone from Intel that works on the Media SDK come up with the list and publish it to this forum instead, every time that a new Intel Graphics driver is released.  This approach would likely produce more useful release notes anyway, since the focus would solely be on those changes that are relevant to the Intel Media SDK.  Ideally, this would also be done retroactively for older driver packages that have already been released.

I mentioned that the release notes can also be confusing or in some cases incorrect.  Here's an example of a confusing or incorrect release note from the 2016 R2 release, depending on one's viewpoint:  "HW Accelerated HEVC decode plugin outputs frames in DXGI_FORMAT_P010 for Microsoft Direct3D 11 and corresponding FOURCC defined format for Direct3D 9. These formats are 16 bit based and valid data bits alignment is different from usual SW codecs."  Perhaps this is true for the MAIN10 profile, although I haven't personally confirmed it, but it isn't true for the MAIN profile, which uses NV12, both as the input to the 6th-generation HEVC encoder and as the output from the HEVC decoder.  Including this kind of incorrect information in the release notes just makes it even more painful to use the Intel Media SDK--it would be better to say nothing than provide incorrect information.

Anyway, I hope that this situation can be improved.

Thanks, AaronL

[Jeffrey_M_Intel1]

Thanks for your feedback on this important topic.  Release notes are a very important channel of communication from the team working on Media SDK to developers using it, so of course we want to make them as effective as possible.  How all of this comes together is complex, so we may not be able to take care of everything you've mentioned all at once.  However, I certainly agree with you that improvements can be made and will start working with the team to see what can be done near and long term.

[Sachin_R_]

@AaronL, you actually hit the bulls eye with this post. This is a serious problem actually!

Many issues are there, but let me list out few. Most of the times, the input params are changed internally and the release notes does not update this. We keep trying to figure out why its not working for hours! Its total waste of everyones' time using something like this.

And even the code quality is an issue! Its very hard to understand whether particular data structure is created by user for a particular sample or is it a media sdk given data structure... There is no standards that are maintained at least in samples provided. Coming from intel, our expectations are very high.. but your samples actually tell us that you have used some arbit developers who have little or no understanding between c & c++ interfaces. Some samples have c, c++ interfaces mixed up abundantly.

You have given documentation which contains 'code samples' embedded in it. Please mention its just pseudo code! We keep looking for the methods mentioned in that 'code'... which never exist!!?? Why tag it as code, then?? Can't you just put a flow chart instead? 

Hope you guys do something on this! Its wasting our valuable time! Can't keep trying forever! :)

[AaronL]

While my post was specifically about the release notes, Sachin R raises a number of good points.  I've stated in the past that no one could use the documentation that comes with the Intel Media SDK to actually create a software solution that uses the Intel Media SDK.  Pretty much all the documentation is in the form of reference documentation, and while that is important, it doesn't tell you how to use it.  I mentioned this to someone from Intel over two years ago at NAB 2014.  Since then, if anything, the documentation has gotten worse, not better.  I understand that it is hard to write good documentation, but I would think that over two years would be enough to improve the documentation.

If the documentation is only good as a reference, then that means that the samples act as actual "documentation", even though, in practice, code samples should support the documentation, not the other way around.  Unfortunately, the samples are a bit too complicated for someone new to the Intel Media SDK.  Instead, the Intel Media SDK tutorials are a much better way to learn the Intel Media SDK.  Tutorials, one might ask, where do I find those?  They are buried a few levels under support on the Web site, at https://software.intel.com/en-us/articles/media-sdk-tutorials-for-client-and-server​ .  Unfortunately, they haven't been kept up-to-date with such things as Skylake HEVC, and some of the code is written in an unnecessarily convoluted fashion, but using the tutorials, I think most capable software engineers could get up and running much more quickly than by using the samples.