mchapman/foobar2000-sdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

add last backwards-compatible version

Browse Source
This commit is contained in:
Mikah Chapman
2021-12-14 00:33:46 -07:00
parent 68b10d413b
commit b0dd3f07f3
335 changed files with 4746 additions and 19627 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
sdk-readme.html
View File

@@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>foobar2000 SDK Readme</title>
<link rel="stylesheet" type="text/css" href="sdk-readme.css" />
</head>
@@ -14,7 +14,7 @@
<div id="toc__inside">
<ul class="toc">
<li class="level1"><div class="li"><span class="li"><a href="#foobar2000_v1.6_sdk_readme" class="toc">foobar2000 v1.6 SDK readme</a></span></div>
<li class="level1"><div class="li"><span class="li"><a href="#foobar2000_v1.4_sdk_readme" class="toc">foobar2000 v1.4 SDK readme</a></span></div>
<ul class="toc">
<li class="level2"><div class="li"><span class="li"><a href="#compatibility" class="toc">Compatibility</a></span></div></li>
<li class="level2"><div class="li"><span class="li"><a href="#microsoft_visual_studio_compatibility" class="toc">Microsoft Visual Studio compatibility</a></span></div>
@@ -23,21 +23,6 @@
<li class="level3"><div class="li"><span class="li"><a href="#virtual_memory_range_for_pch_exceeded_error" class="toc">&quot;virtual memory range for PCH exceeded&quot; error</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.6_notes" class="toc">Version 1.6 notes</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#windows_xp_support" class="toc">Windows XP support</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#audio_output_api_extensions" class="toc">Audio output API extensions</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#webp_support_imageloaderlite" class="toc">WebP support, imageLoaderLite</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#file_cache_utilities" class="toc">File cache utilities</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#cuesheet_wrapper_fixes" class="toc">Cuesheet wrapper fixes</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#libppui" class="toc">libPPUI</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.5_notes" class="toc">Version 1.5 notes</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#libppui1" class="toc">libPPUI</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.4_notes" class="toc">Version 1.4 notes</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#namespace_cleanup" class="toc">Namespace cleanup</a></span></div></li>
@@ -70,16 +55,20 @@
<h1><a name="foobar2000_v1.6_sdk_readme" id="foobar2000_v1.6_sdk_readme">foobar2000 v1.6 SDK readme</a></h1>
<h1><a name="foobar2000_v1.4_sdk_readme" id="foobar2000_v1.4_sdk_readme">foobar2000 v1.4 SDK readme</a></h1>
<div class="level1">
</div>
<!-- SECTION "foobar2000 v1.6 SDK readme" [1-42] -->
<!-- SECTION "foobar2000 v1.4 SDK readme" [1-42] -->
<h2><a name="compatibility" id="compatibility">Compatibility</a></h2>
<div class="level2">
<p>
Components built with this <acronym title="Software Development Kit">SDK</acronym> are compatible with foobar2000 1.4 and newer. They are not compatible with any earlier versions (will fail to load), and not guaranteed to be compatible with any future versions, though upcoming releases will aim to maintain compatibility as far as possible without crippling newly added functionality.
Components built with this <acronym title="Software Development Kit">SDK</acronym> are compatible with foobar2000 1.3 and 1.4 series. They are not compatible with any earlier versions (will fail to load), and not guaranteed to be compatible with any future versions, though upcoming releases will aim to maintain compatibility as far as possible without crippling newly added functionality.
</p>
<p>
Note that components built with this <acronym title="Software Development Kit">SDK</acronym> can provide foobar2000 1.4 functionality while maintaining compatibility with the 1.3 series.
</p>
<p>
@@ -87,11 +76,15 @@ You can alter the targeted foobar2000 <acronym title="Application Programming In
</p>
<p>
Currently supported values are 79 (for 1.4 series) and 80 (for 1.5 &amp; 1.6 series).
Currently supported values are 78 (for 1.3 series) and 79 (for 1.4 series).
</p>
<p>
<acronym title="Application Programming Interface">API</acronym> 78 components load in foobar2000 1.3 and 1.4; <acronym title="Application Programming Interface">API</acronym> 79 components load in 1.4 only.
</p>
</div>
<!-- SECTION "Compatibility" [43-610] -->
<!-- SECTION "Compatibility" [43-832] -->
<h2><a name="microsoft_visual_studio_compatibility" id="microsoft_visual_studio_compatibility">Microsoft Visual Studio compatibility</a></h2>
<div class="level2">
@@ -100,7 +93,7 @@ Currently supported values are 79 (for 1.4 series) and 80 (for 1.5 &amp; 1.6 ser
</p>
</div>
<!-- SECTION "Microsoft Visual Studio compatibility" [611-718] -->
<!-- SECTION "Microsoft Visual Studio compatibility" [833-940] -->
<h3><a name="ill_behavior_of_visual_c_whole_program_optimization" id="ill_behavior_of_visual_c_whole_program_optimization">Ill behavior of Visual C whole program optimization</a></h3>
<div class="level3">
@@ -113,7 +106,7 @@ If you&#039;re aware of a better workaround - such as a source code change rathe
</p>
</div>
<!-- SECTION "Ill behavior of Visual C whole program optimization" [719-1498] -->
<!-- SECTION "Ill behavior of Visual C whole program optimization" [941-1720] -->
<h3><a name="virtual_memory_range_for_pch_exceeded_error" id="virtual_memory_range_for_pch_exceeded_error">&quot;virtual memory range for PCH exceeded&quot; error</a></h3>
<div class="level3">
@@ -126,101 +119,22 @@ The <acronym title="Software Development Kit">SDK</acronym> has been changed to
</p>
<p>
If you run into this error, we recommend trimming down the #includes and only referencing specific headers from helpers instead of #including all of them (via old helpers.h).
If you run into this error, we recommend the following steps:
</p>
<ul>
<li class="level1"><div class="li"> ATLHelpers: do not #include ATLHelpers/ATLHelpers.h - use ATLHelpersLean.h instead + additional ones on need-to-use basis.</div>
</li>
<li class="level1"><div class="li"> Helpers: do not #include helpers.h, #include individual ones as needed; most of the declare functionality needed for very specific components only.</div>
</li>
</ul>
</div>
<!-- SECTION "virtual memory range for PCH exceeded error" [1499-2150] -->
<h2><a name="version_1.6_notes" id="version_1.6_notes">Version 1.6 notes</a></h2>
<div class="level2">
</div>
<!-- SECTION "Version 1.6 notes" [2151-2180] -->
<h3><a name="windows_xp_support" id="windows_xp_support">Windows XP support</a></h3>
<div class="level3">
<p>
The <acronym title="Software Development Kit">SDK</acronym> project files are configured for targetting Windows 7 and newer, with SSE2 level instruction set.
</p>
<p>
If you really must compile components that run on 20 years old computers, you can still change relevant settings, or use an older <acronym title="Software Development Kit">SDK</acronym>. Please test your components on actual hardware if you do so, VS2017 compiler has been known to output SSE opcodes when specifically told not to.
</p>
</div>
<!-- SECTION "Windows XP support" [2181-2597] -->
<h3><a name="audio_output_api_extensions" id="audio_output_api_extensions">Audio output API extensions</a></h3>
<div class="level3">
<p>
New methods have been added to the output <acronym title="Application Programming Interface">API</acronym>, such as reporting whether your output is low-latency or high-latency, to interop with the new fading code.
</p>
<p>
foobar2000 now provides a suite of special fixes for problematic output implementations (guarenteed update() calls in regular intervals, silence injected at the end); use flag_needs_shims to enable with your output. While such feature might seem unnecessary, it allowed individual outputs to be greatly simplified, removing a lot of other special fixes implemented per output.
</p>
</div>
<!-- SECTION "Audio output API extensions" [2598-3169] -->
<h3><a name="webp_support_imageloaderlite" id="webp_support_imageloaderlite">WebP support, imageLoaderLite</a></h3>
<div class="level3">
<p>
Use fb2k::imageLoaderLite <acronym title="Application Programming Interface">API</acronym> to load a Gdiplus image from a memory block, or to extract info without actually decoding the picture. It supports WebP payload and will be updated with any formats added in the future.
</p>
</div>
<!-- SECTION "WebP support, imageLoaderLite" [3170-3426] -->
<h3><a name="file_cache_utilities" id="file_cache_utilities">File cache utilities</a></h3>
<div class="level3">
<p>
New interface has been introduced - read_ahead_tools - to access advanced playback settings for read-ahead cache; primarily needed if your decoder needs to open additional files over the internet.
</p>
</div>
<!-- SECTION "File cache utilities" [3427-3655] -->
<h3><a name="cuesheet_wrapper_fixes" id="cuesheet_wrapper_fixes">Cuesheet wrapper fixes</a></h3>
<div class="level3">
<p>
Wrapper code to support embedded cuesheets on arbitrary formats has been updated to deal with remote files gracefully, that is not present any chapters on such.
</p>
</div>
<!-- SECTION "Cuesheet wrapper fixes" [3656-3850] -->
<h3><a name="libppui" id="libppui">libPPUI</a></h3>
<div class="level3">
<p>
Notable changes: * WebP vs Gdiplus interop (in case you want to load WebP into Gdiplus in your own app - in fb2k, use imageLoaderLite) * Fixed horrible GdiplusImageFromMem() bug * Combo boxes in CListControl * CListControl graying/disabling of individual items
</p>
</div>
<!-- SECTION "libPPUI" [3851-4130] -->
<h2><a name="version_1.5_notes" id="version_1.5_notes">Version 1.5 notes</a></h2>
<div class="level2">
</div>
<!-- SECTION "Version 1.5 notes" [4131-4160] -->
<h3><a name="libppui1" id="libppui1">libPPUI</a></h3>
<div class="level3">
<p>
Various code from the helpers projects that was in no way foobar2000 specific became libPPUI. In addition, Default User Interface list control has been thrown in. libPPUI is released under a non-restrictive license. Reuse in other projects - including commercial projects - is encouraged. Credits in binary redistribution are not required.
</p>
<p>
Existing foobar2000 components that reference <acronym title="Software Development Kit">SDK</acronym> helpers/ATLHelpers will need updating to reference libPPUI instead. Separate helpers/ATLHelpers projects are no more, as all projects depend on libPPUI which requires ATL/WTL.
</p>
</div>
<!-- SECTION "libPPUI" [4161-4746] -->
<!-- SECTION "virtual memory range for PCH exceeded error" [1721-2538] -->
<h2><a name="version_1.4_notes" id="version_1.4_notes">Version 1.4 notes</a></h2>
<div class="level2">
</div>
<!-- SECTION "Version 1.4 notes" [4747-4776] -->
<!-- SECTION "Version 1.4 notes" [2539-2568] -->
<h3><a name="namespace_cleanup" id="namespace_cleanup">Namespace cleanup</a></h3>
<div class="level3">
@@ -229,7 +143,7 @@ Some very old inconsistencies in the code have been cleaned up. Various bit_arra
</p>
</div>
<!-- SECTION "Namespace cleanup" [4777-5126] -->
<!-- SECTION "Namespace cleanup" [2569-2918] -->
<h3><a name="decoders" id="decoders">Decoders</a></h3>
<div class="level3">
@@ -261,7 +175,7 @@ The proper way to instantiate any input related classes is to call input_manager
<div class="level5">
<p>
If your component targets <acronym title="Application Programming Interface">API</acronym> level lower than 79, all your attempts to walk input_entry services return a shim service that redirects all your calls to input_manager. You cannot walk actual input_entry services.
If your component targets <acronym title="Application Programming Interface">API</acronym> level lower than 79 (this <acronym title="Software Development Kit">SDK</acronym> comes configured for 78 by default), all your attempts to walk input_entry services return a shim service that redirects all your calls to input_manager. You cannot walk actual input_entry services.
</p>
<p>
@@ -311,7 +225,7 @@ typedef input_info_writer_v2 interface_info_writer_t;
</pre>
</div>
<!-- SECTION "Decoders" [5127-7762] -->
<!-- SECTION "Decoders" [2919-5600] -->
<h3><a name="dynamic_runtime" id="dynamic_runtime">Dynamic runtime</a></h3>
<div class="level3">
@@ -320,11 +234,11 @@ As of version 1.4, foobar2000 is compiled with dynamic Visual C runtime and redi
</p>
<p>
This <acronym title="Software Development Kit">SDK</acronym> comes configured for dynamic runtime by default. If you wish to support foobar2000 versions older than 1.4, change to static runtime or make sure that your users have the runtime installed.
This <acronym title="Software Development Kit">SDK</acronym> comes configured for static runtime by default, for compatibility with foobar2000 version 1.3. If your component is for foobar2000 series 1.4 only, you can switch to using dynamic runtime instead - make sure to change the setting for all projects in your workspace.
</p>
</div>
<!-- SECTION "Dynamic runtime" [7763-8303] -->
<!-- SECTION "Dynamic runtime" [5601-6217] -->
<h3><a name="service_query" id="service_query">service_query()</a></h3>
<div class="level3">
@@ -377,7 +291,7 @@ You can use it to avoid having to supply service_query() code yourself and possi
</p>
</div>
<!-- SECTION "service_query()" [8304-10014] -->
<!-- SECTION "service_query()" [6218-7928] -->
<h2><a name="version_1.3_notes" id="version_1.3_notes">Version 1.3 notes</a></h2>
<div class="level2">
@@ -404,7 +318,7 @@ It is recommended that you change your existing code using these to obtain track
</p>
</div>
<!-- SECTION "Version 1.3 notes" [10015-10770] -->
<!-- SECTION "Version 1.3 notes" [7929-8684] -->
<h2><a name="basic_usage" id="basic_usage">Basic usage</a></h2>
<div class="level2">
@@ -442,12 +356,14 @@ Component code should include the following header files:
<ul>
<li class="level1"><div class="li"> foobar2000.h from <acronym title="Software Development Kit">SDK</acronym> - do not include other headers from the <acronym title="Software Development Kit">SDK</acronym> directory directly, they&#039;re meant to be referenced by foobar2000.h only; it also includes PFC headers and shared.dll helper declaration headers.</div>
</li>
<li class="level1"><div class="li"> Necessary headers from libPPUI and helpers, which both contain various code commonly used by fb2k components.</div>
<li class="level1"><div class="li"> Optionally: helpers.h from helpers directory (foobar2000_<acronym title="Software Development Kit">SDK</acronym>_helpers project) - a library of various helper code commonly used by foobar2000 components.</div>
</li>
<li class="level1"><div class="li"> Optionally: ATLHelpers.h from ATLHelpers directory (foobar2000_ATL_helpers project) - another library of various helper code commonly used by foobar2000 components; requires WTL. Note that ATLHelpers.h already includes <acronym title="Software Development Kit">SDK</acronym>/foobar2000.h and helpers/helpers.h so you can replace your other include lines with a reference to ATLHelpers.h.</div>
</li>
</ul>
</div>
<!-- SECTION "Basic usage" [10771-12139] -->
<!-- SECTION "Basic usage" [8685-10436] -->
<h2><a name="structure_of_a_component" id="structure_of_a_component">Structure of a component</a></h2>
<div class="level2">
@@ -456,7 +372,7 @@ Component code should include the following header files:
</p>
</div>
<!-- SECTION "Structure of a component" [12140-12306] -->
<!-- SECTION "Structure of a component" [10437-10603] -->
<h3><a name="services" id="services">Services</a></h3>
<div class="level3">
@@ -473,7 +389,7 @@ Each service object provides reference counter features and (<code>service_add_r
</p>
</div>
<!-- SECTION "Services" [12307-14572] -->
<!-- SECTION "Services" [10604-12869] -->
<h3><a name="entrypoint_services" id="entrypoint_services">Entrypoint services</a></h3>
<div class="level3">
@@ -515,7 +431,7 @@ A typical entrypoint service implementation looks like this:
<span class="br0">&#125;</span>;
<span class="kw4">static</span> service_factory_single_t&lt;myservice_impl&gt; g_myservice_impl_factory;</pre>
</div>
<!-- SECTION "Entrypoint services" [14573-17030] -->
<!-- SECTION "Entrypoint services" [12870-15327] -->
<h3><a name="service_extensions" id="service_extensions">Service extensions</a></h3>
<div class="level3">
@@ -533,7 +449,7 @@ service_ptr_t&lt;myservice_v2&gt; ptr_ex;
<span class="kw1">if</span> <span class="br0">&#40;</span>ptr-&gt;service_query_t<span class="br0">&#40;</span>ptr_ex<span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span> <span class="coMULTI">/* ptr_ex is a valid pointer to myservice_v2 interface of our myservice instance */</span> <span class="br0">&#40;</span>...<span class="br0">&#41;</span> <span class="br0">&#125;</span>
<span class="kw1">else</span> <span class="br0">&#123;</span><span class="coMULTI">/* this myservice implementation does not implement myservice_v2 */</span> <span class="br0">&#40;</span>...<span class="br0">&#41;</span> <span class="br0">&#125;</span></pre>
</div>
<!-- SECTION "Service extensions" [17031-17970] -->
<!-- SECTION "Service extensions" [15328-16267] -->
<h3><a name="autopointer_template_use" id="autopointer_template_use">Autopointer template use</a></h3>
<div class="level3">
@@ -550,7 +466,7 @@ When working with pointers to core fb2k services, just use C++11 <code>auto</cod
</p>
</div>
<!-- SECTION "Autopointer template use" [17971-18538] -->
<!-- SECTION "Autopointer template use" [16268-16835] -->
<h3><a name="exception_use" id="exception_use">Exception use</a></h3>
<div class="level3">
@@ -567,7 +483,7 @@ Implementations of global callback services such as <code>playlist_callback</cod
</p>
</div>
<!-- SECTION "Exception use" [18539-19556] -->
<!-- SECTION "Exception use" [16836-17853] -->
<h3><a name="storing_configuration" id="storing_configuration">Storing configuration</a></h3>
<div class="level3">
@@ -584,7 +500,7 @@ Note that <code>cfg_var</code> objects can only be instantiated statically (eith
</p>
</div>
<!-- SECTION "Storing configuration" [19557-20492] -->
<!-- SECTION "Storing configuration" [17854-18789] -->
<h3><a name="use_of_global_callback_services" id="use_of_global_callback_services">Use of global callback services</a></h3>
<div class="level3">
@@ -634,7 +550,7 @@ You should also avoid firing a cross-thread SendMessage() inside global callback
</p>
</div>
<!-- SECTION "Use of global callback services" [20493-22914] -->
<!-- SECTION "Use of global callback services" [18790-21211] -->
<h2><a name="service_class_design_guidelines_advanced" id="service_class_design_guidelines_advanced">Service class design guidelines (advanced)</a></h2>
<div class="level2">
@@ -643,7 +559,7 @@ You should also avoid firing a cross-thread SendMessage() inside global callback
</p>
</div>
<!-- SECTION "Service class design guidelines (advanced)" [22915-23251] -->
<!-- SECTION "Service class design guidelines (advanced)" [21212-21548] -->
<h3><a name="cross-dll_safety" id="cross-dll_safety">Cross-DLL safety</a></h3>
<div class="level3">
@@ -652,7 +568,7 @@ You should also avoid firing a cross-thread SendMessage() inside global callback
</p>
</div>
<!-- SECTION "Cross-DLL safety" [23252-24079] -->
<!-- SECTION "Cross-DLL safety" [21549-22376] -->
<h3><a name="entrypoint_service_efficiency" id="entrypoint_service_efficiency">Entrypoint service efficiency</a></h3>
<div class="level3">
@@ -719,6 +635,6 @@ service_ptr_t&lt;myservice_instance&gt; findservice<span class="br0">&#40;</span
throw exception_io_data<span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="br0">&#125;</span></pre>
</div>
<!-- SECTION "Entrypoint service efficiency" [24080-] --></div>
<!-- SECTION "Entrypoint service efficiency" [22377-] --></div>
</body>
</html>