README.upgrading for Widevine CDM Partner Kit v2.1
Date: 7/02/2014

This document provides details on important changes between versions of the
Widevine CDM.  Some upgrades may require you to make changes to your
application, so please read carefully.

NOTE: All gyp variables have default values in platforms/global_config.gypi.
You may override these defaults in your platform-specific gypi.


New in v2.1.4:
=====
New gyp variables have been introduced to make the build more configurable:
  * protobuf_gyp
    For gyp-based projects with their own internal version of protobuf, allows
    the path to the protobuf gyp file to be overridden.  The default is
    third_party/protobuf.gyp.  Ignored if use_system_protobuf is 'true'.


New in v2.1.3:
=====
New gyp variables have been introduced to make the build more configurable:
  * oemcrypto_v8
    The current version of OEMCrypto is v9.  Set to 'true' if your system
    supplies OEMCrypto v8.  Defaults to 'false'.

The CDM interface (class ContentDecryptionModule) has been simplified.
The following methods have been removed:
  * InitializeAudioDecoder()
  * InitializeVideoDecoder
  * DeinitializeDecoder
  * ResetDecoder
  * DecryptAndDecodeFrame
  * DecryptAndDecodeSamples

The Host interface (class Host) has been simplified.
The following methods have been removed:
  * GetPrivateData
  * PersistPlatformString
  * GetPlatformByteArray
  * SetPlatformByteArray
  * PersistPlatformByteArray

The following Host methods have changed:
  * GetPlatformString
    Now does the job of GetPlatformByteArray as well.
  * SetPlatformString
    Now does the job of SetPlatformByteArray, PersistPlatformString, and
    PersistPlatformByteArray as well.
  * SetTimer
    This should schedule a single callback, not a repeating timer.  Multiple
    timer callbacks may be scheduled by the CDM at once.  All callbacks should
    occur serially on the same thread/queue as all other calls into the CDM.


New in v2.1.2:
=====
The following file locations have changed:

  ./cdm/cdm_api_internal.gyp => ./cdm/cdm.gyp
  ./cdm/cdm_api_external.gyp => ./cdm/cdm_unittests.gyp

If you have your own gyp files which depend on CDM targets, please update them
accordingly.

./build.py will use the ninja build tool if available.  Otherwise, it will
continue to use make.

The Host is no longer expected to allocate a Buffer before calling
ContentDecryptionModule::Decrypt.  The CDM will now call Host::Allocate and
DecryptedBlock::SetBuffer as needed in its Decrypt method.  To avoid the
potential for a memory leak, make sure that your Host implementation no
longer allocates a Buffer before calling Decrypt.

For more details on the Host interface, see "Widevine Security Integration
Guide for CENC: EME Supplement".


New in v2.1.1:
=====
The following file locations have changed:

  ./build/build.py => ./build.py
  ./build/platforms/ => ./platforms/
  ./build/global_config.gypi => ./platforms/global_config.gypi
  ./build/protoc.gypi => ./third_party/protoc.gypi

The file ./build/platforms/cdm_platforms.py no longer exists.  Platform
definitions are now based on the folder structure in ./platforms rather than
a python-based config file.

The OEMCrypto interface has been updated to v9, and documentation has been
updated in oemcrypto/include.  The following functions were added:

  * OEMCrypto_GetHDCPCapability
  * OEMCrypto_SupportsUsageTable
  * OEMCrypto_UpdateUsageTable
  * OEMCrypto_DeactivateUsageEntry
  * OEMCrypto_ReportUsage
  * OEMCrypto_DeleteUsageEntry
  * OEMCrypto_DeleteUsageTable

The file ./platforms/x86-64/x86-64.gypi now contains examples of how settings
can be customized for a given platform.

New gyp variables have been introduced to make the build more configurable:
  * use_system_protobuf
    Allows building protobuf from source, rather than using a system-wide
    installation of the library and its tools.  Defaults to 'true'.
  * protobuf_source_dir
    The path to the protobuf sources.  Ignored if use_system_protobuf is
    'true'.  The source dir is expected to have a valid config.h for the
    platform.