From 0a80d901860f2edf96f9db3aa8c97645fa7b10cd Mon Sep 17 00:00:00 2001 From: omicron Date: Fri, 19 May 2023 18:35:26 +0200 Subject: [PATCH] Add readme --- README.md | 216 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9e0a927 --- /dev/null +++ b/README.md @@ -0,0 +1,216 @@ +# LibFreeMedia + +LibFreeMedia is a small library to facilitate the sharing of media resources +between different World of Warcraft addons. It was developed to provide a free +software alternative to the proprietary LibSharedMedia. + +Sharing media works best for both users as well as addon developers if everyone +can access the shared media pool equally, and this includes authors that want +to release their addons as free software. Therefore this library interoperates +with LibShareMedia. Media registered using one library can be retrieved with +the other and vice versa. See [Interopability](#interopability) for the +limitations of this interopability. + +# API + +LibFreeMedia registers as a library using LibStub. Use LibStub to acquire a +handle to the libary: +```lua +local lib = LibStub:GetLibrary("LibFreeMedia") +``` + +## Registering Media + +```lua +lib:Register(kind, identifier, data) +``` + +### Arguments + + * *kind* (string): the kind of media you are registering. Some examples are + "font", "background" or "statusbar" + * *identifier* (string): The (unique among its kind) name to identify the + media. Users will often see this name, so use a descriptive name. + * *data* (any): The data that represents the media. After it is registered + the library takes ownership of the data and it _must not_ be changed. + +### Return value + +The return value is a boolean indicating whether the media was registered +successfully. Failure may happen for a number of reasons, including registering +invalid data or the identifier already has registered media for that kind. + +### Example + +```lua +local libfm = LibStub:GetLibrary("LibFreeMedia") +libfm:Register("font", "Roboto Regular", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Regular.ttf") +libfm:Register("font", "Roboto Bold", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Bold.ttf") + +if not libfm:Register("font", "Roboto Bold", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Bold.ttf") then + error("The media registration failed") +end +``` + +## Getting individual media + +```lua +lib:Get(kind, identifier) +``` + +### Arguments + + * *kind* (string): the kind of media you want to retrieve. Some examples are + "font", "background" or "statusbar". + * *identifier* (string): The name of the media you want to retrieve. + +### Return value + +If the media exists, its data is returned. The type of this data depends on the +kind of media. LibFreeMedia retains ownership of this data and you _must not_ +alter it in place. + +If the media does not exist the function will return `nil`. + +### Examples + +```lua +local libfm = LibStub:GetLibrary("LibFreeMedia") + +local robotoRegular = libfm:Get("font", "Roboto Regular") +if robotoRegular then + print("Successfully got the font location:", robotoRegular) +else + print("The 'Roboto Regular' font could not be retrieved") +end +``` + +## Getting a list of media identifiers + +```lua +lib:GetList(kind) +``` + +### Arguments + + * *kind* (string): the kind of media you want to get a list of. Some examples + are "font", "background" or "statusbar". + +### Return value + +If there is media registered for the requested kind it will be returned as a +sorted sequence table of media identifiers for the requested kind. If there is +no media of the requested kind then this function will return either `nil` or +an empty table. + +LibSharedMedia retains ownership of the returned tables and they should not be +altered in place. These tables may be reused by LibSharedMedia and and media +that is registered in the future could be added to these tables but this behavior +_should not_ be relied on. If you require an up to date list, call the +library to receive one. If you require a snapshot to remain static, make a deep +copy. + +### Examples + +```lua +local libfm = LibStub:GetLibrary("LibFreeMedia") + +local fonts = libfm:GetList("font") +if fonts == nil or #fonts == 0 then + print("No registered fonts found") +else + print("Registered fonts", table.concat(fonts, ", ")) +end +``` + +## Getting a table of media data + +```lua +lib:GetTable(kind) +``` + +### Arguments + + * *kind* (string): the kind of media you want to get a list of. Some examples + are "font", "background" or "statusbar". + +### Return value + +If there is media registered for the requested kind it will be returned as a +table with identifier:data pairs. If there is no media of the requested kind +then this function will return either `nil` or an empty table. + +LibSharedMedia retains ownership of the returned tables and they should not be +altered in place. These tables may be reused by LibSharedMedia and and media +that is registered in the future could be added to these tables but this behavior +_should not_ be relied on. If you require an up to date list, call the +library to receive one. If you require a snapshot to remain static, make a deep +copy. + +### Examples + +```lua +local libfm = LibStub:GetLibrary("LibFreeMedia") + +local fonts = libfm:GetTable("font") or {} + +for identifier, data in pairs(fonts) do + print(identifier, data) +end +``` + +# Embedding LibFreeMedia + +The recommended way to include LibFreeMedia in your addon is embedding it and +getting a handle using LibStub. To do this you To do this simply grab one of +the embed archives from the +[releases](https://gitlab.com/omicron-oss/wow/libfreemedia/-/releases) and +extract these files in your addon. Do the same with +[LibStub](https://www.wowace.com/projects/libstub). This will get you a +directory tree similar to the following: + +``` +YourAddon/libs/LibFreeMedia/LibFreeMedia.lua +YourAddon/libs/LibStub/LibStub.lua +YourAddon/YourAddon.toc +... +``` + +Simply add `LibStub.lua` and `LibFreeMedia.lua` as the first few files in your +`YourAddon.toc` as follows: + +``` +## Interface: 100100 +## Title: YourAddon +## Version: 4.20.69 + +# List LibStub and then LibFreeMedia +libs/LibStub/LibStub.lua +libs/LibStub/LibFreeMedia.lua + +# List all your addon files as desired +``` + +# Interopability + +Since it is in the interested of both users and developers to not create +additional pools for shared media, LibFreeMedia attempts to interoperate +seamlessly with LibSharedMedia. However, there is no 100% parity between +LibFreeMedia and LibSharedMedia. This section will list all the areas where +LibFreeMedia differs from LibSharedMedia. + +LibFreeMedia does not support making callbacks on media registration. Any addon +that relies on these callbacks in LibSharedMedia will currently not receive +notifications when media is registered using LibFreeMedia. This is likely +temporary, see issue #1. + +LibFreeMedia does not support default return values for missing media, nor does +it allow you to register a particular piece of media as the default for a +specific kind. + +LibFreeMedia does not support language masks for font registration. This is not +likely to change. + +LibFreeMedia does not attempt to be a drop-in replacement for LibSharedMedia. +The API behaves slightly different. If there is demand for a drop-in +replacement then this could change.