Winamp Developer Wiki - User contributions [en]

Winamp Developer Network Wiki Terms and Conditions

2008-10-10T13:50:50Z

Tarik: /* About These Terms */

==Winamp Developer Network Wiki Terms and Conditions==

Welcome! The following terms govern your access, use and participate in Winamp’s Developer Network Wiki (“Wiki Service”).

BY REGISTERING OR BY USING THE WIKI SERVICE, YOU SIGNIFY ELECTRONICALLY YOUR AGREEMENT TO THE FOLLOWING TERMS. If you do not agree, you may not use the Wiki Service.

==About the Developer Network Wiki==

The Wiki Service is a centralized resource that offers a consolidation of Winamp documentation, code samples, reference materials, and sample articles and gives the development community a place to share information. We offer the Wiki Service to help facilitate the development of Winamp skins, plugins, and visualization presets.

==About These Terms==

The Wiki Service is provided by Nullsoft, Inc. and its affiliates (collectively, “we” or “us”). In order to use the Wiki Service, you must abide by Nullsoft Terms of Use for Winamp.com (http://www.winamp.com/legal/terms), the supplemental Wiki terms below, the Wiki Policy and Guidelines located at (http://dev.winamp.com/wiki/Policies_%26_Guidelines) and such other policies that we may post from time to time on the Wiki Service. These terms collectively make up your agreement with us regarding your access and use the Wiki Service (the “Terms”). We may change these Terms at any time. Your ongoing use of the Wiki Service after we post or notify you about changes to our terms signifies your agreement electronically to the updated terms.

==Your requirements==

In order to use the Wiki Service, you must register with us and provide complete, accurate and current information about yourself. You must keep this information up to date at all times. You must comply at all times with applicable laws and these Terms.

==Use of Information==

The Winamp Privacy Policy located at http://www.winamp.com/legal/privacy explains the practices that apply to your information when you use the Wiki Service. Your ongoing use of the Wiki Service signifies your consent to the information practices disclosed in our Privacy Policy.

==Use of Wiki Service==

You may not submit or transmit through the Wiki Service any material, or otherwise engage in any conduct that:
#violates or infringes the rights of others including, without limitation, patent, trademark, trade secret, copyright, publicity or other proprietary rights,
#is unlawful, threatening, abusive, harassing, defamatory, libelous, deceptive, fraudulent, invasive of another's privacy, tortious, or contains explicit or graphic descriptions, or accounts of, sexual acts,
#victimizes, harasses, degrades, or intimidates an individual or group of individuals on the basis of religion, gender, sexual orientation, race, ethnicity, age, or disability,
#impersonates any person, business or entity,
#contains viruses or any other malicious computer code,
#encourages conduct that would constitute a criminal offense, or that gives rise to civil liability,
#transmits, directly or indirectly, any unsolicited bulk communications (including e-mails, “spam” and instant messages),
#violates these Terms, including without limitation, the Nullsoft Terms of Use for Winamp.com, or
#interferes with the use of the Wiki Service or any other area on Winamp.com by others.

==Ownership==

The content on Wiki Service including, without limitation, images, graphics, audio, music, videos, texts, software, feedback, data, messages, answers, questions, comments, suggestions, ideas or any other materials (“Content”) are owned or licensed by us and protected under copyright and other intellectual property right laws. All trade names, trademarks and service marks appearing on the Content are protected by Nullsoft, Inc., its parent and affiliates or respective third party owners. Any rights not expressly granted herein are reserved. All Content is for your application development purposes and for your personal use only and may not be modified, reproduced, transmitted, published, exploited, sold, licensed or distributed to any third parties or in combination with any applications if the Content would constitute the primary value of the product being distributed.

==Submissions==

The Wiki Service allows users to upload, download, edit, host, share and/or publish Content (“User Content”). We may, in our sole discretion, incorporate such User Content into any of our products or services.

You are solely responsible for any submission of User Content. You may only submit User Content that you own or that you have acquired such consents, permissions or licenses needed to submit such Content. If your User Content contains content of a third party or open source material, you shall clearly notify us of such third-party material together with any license terms that deviate from those specified in these Terms, as well as be responsible for acquiring consent for such use the User Content. Any such third party content or open source material shall be subject to your obligation to indemnify us. Upon submission of any User Content to the Wiki Service, you will grant us and our parent a worldwide, perpetual, irrevocable, royalty-free, non-exclusive, assignable and sublicensable license to use, reproduce, modify, create derivative works, publicly perform and display such User Content in connection with any of our products or services, entirely without obligation, compensation or restriction of any kind.

==No Duty to Monitor==

You agree that we are not liable for Content (including User Content) that is provided by others. We have no duty to pre-screen Content, but we have the right to refuse to post or to edit submitted Content. We reserve the right to remove Content for any reason, but we are not responsible for any failure or delay in removing such material.

==Procedure for Making Claims of Copyright Infringement.==

We respect the intellectual property of others. If you believe that your work has been copied and is accessible on the Wiki Service in a way that constitutes copyright infringement, please click here <http://about.aol.com/aolnetwork/copyright_infringement> for instructions on how to contact us to report possible copyright infringement.

==No Warranties==

We provide the Wiki Service "as is", "with all faults" and "as available." You use the Content and Wiki Service at your own risk. We and our suppliers and distributors make no express warranties or guarantees about the Wiki Service. TO THE EXTENT PERMITTED BY LAW, WE AND OUR SUPPLIERS DISCLAIM IMPLIED WARRANTIES THAT THE WIKI SERVICE ARE MERCHANTABLE, OF SATISFACTORY QUALITY, ACCURATE, TIMELY, FIT FOR A PARTICULAR PURPOSE OR NEED, OR NON-INFRINGING. WE DO NOT GUARANTEE THAT THE WIKI SERVICE WILL MEET YOUR REQUIREMENTS, IS ERROR-FREE, RELIABLE, WITHOUT INTERRUPTION OR AVAILABLE AT ALL TIMES. WE DO NOT GUARANTEE THAT THE RESULTS THAT MAY BE OBTAINED FROM THE WIKI SERVICE OR THAT YOU WILL BE ABLE TO ACCESS THE WIKI SERVICE AT ALL TIMES. You may have additional consumer rights under your local laws that this contract cannot change.

==Limitation of Liability==

YOUR SOLE AND EXCLUSIVE REMEDY FOR ANY DISPUTE WITH US IS TO DISCONTINUE YOUR USE OF THE WIKI SERVICE. WE, OUR PARENT, AND OUR SUPPLIERS SHALL NOT BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES ARISING FROM YOUR USE OF, INABILITY TO USE, OR RELIANCE UPON AOL.COM. THESE EXCLUSIONS APPLY TO ANY CLAIMS FOR LOST PROFITS, LOST DATA, LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF WE KNEW OR SHOULD HAVE KNOWN OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR THE LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, IN SUCH STATES OR JURISDICTIONS, OUR LIABILITY, AND THE LIABILITY OF OUR PARENT AND SUPPLIERS, SHALL BE LIMITED TO THE EXTENT PERMITTED BY LAW.

==Indemnification==

Upon a request by us, you agree to defend, indemnify, and hold harmless us and our parent and other affiliated companies, and our respective employees, contractors, officers, directors, and agents from all liabilities, claims, and expenses, including attorney's fees that arise from your use or misuse of the Wiki Service. We reserve the right, at our own expense, to assume the exclusive defense and control of any matter otherwise subject to indemnification by you, in which event you will cooperate with us in asserting any available defenses.

==International Use==

We make no representation that Content on the Wiki Service is appropriate or available for use in locations outside the United States, and accessing it from territories where the Content is illegal is prohibited. If you choose to access the Wiki Service from a location outside the U.S., you do so on your own initiative and you are responsible for compliance with local laws.

==Software Restrictions==

Any software offered through the Wiki Service is a "commercial item," as that term is defined in 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation," as such terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 27.405(b)(2) (June 1998) and 48 C.F.R. 227.7202, all U.S. Government end users acquire the software with only those rights as set forth herein. You agree to fully comply with all import and export laws, regulations, rules and orders of the United States, or any foreign government agency or authority, and that you will not directly or indirectly export, re-export, transfer and/or release the software, related technology, or any product thereof, for any proscribed end-use, or to any proscribed country, entity or person (wherever located), without proper authorization from the U.S. and/or foreign government.

==Choice of Law==

You agree that the laws of the Commonwealth of Virginia govern this contract and any claim or dispute that you may have against us, without regard to Virginia’s conflict of laws rules, and that the United Nations Convention on Contracts for the International Sale of Goods shall have no applicability. You further agree that any disputes or claims that you may have against us will be resolved by a court located in the Commonwealth of Virginia and you agree and submit to the exercise of personal jurisdiction of such courts for the purpose of litigating any such claim or action. PLEASE NOTE THAT BY AGREEING TO THESE TERMS OF USE, YOU ARE: (1) WAIVING CLAIMS THAT YOU MIGHT OTHERWISE HAVE AGAINST US BASED ON THE LAWS OF OTHER JURISDICTIONS, INCLUDING YOUR OWN; (2) IRREVOCABLY CONSENTING TO THE EXCLUSIVE JURISDICTION OF, AND VENUE IN, STATE OR FEDERAL COURTS IN THE COMMONWEALTH OF VIRGINIA OVER ANY DISPUTES OR CLAIMS YOU HAVE WITH US; AND (3) SUBMITTING YOURSELF TO THE PERSONAL JURISDICTION OF COURTS LOCATED IN THE COMMONWEALTH OF VIRGINIA FOR THE PURPOSE OF RESOLVING ANY SUCH DISPUTES OR CLAIMS.

==Termination==

Your right to use the Wiki Service automatically terminates if you violate these Terms or any rules or guidelines posted in connection with AOL.COM. We also reserve the right, in our sole discretion, to terminate your access to all or part of the Wiki Service, for any reason, with or without notice.

==Electronic Notices==

YOU AGREE TO TRANSACT WITH US ELECTRONICALLY. WE MAY PROVIDE NOTICES TO YOU ELECTRONICALLY (1) VIA E-MAIL IF YOU HAVE PROVIDED US WITH A VALID EMAIL ADDRESS OR (2) BY POSTING THE NOTICE ON A WEBSITE DESIGNATED BY US FOR THIS PURPOSE. The delivery of any Notice is effective when sent or posted by us, regardless of whether you read the Notice or actually receive delivery. You can withdraw your consent to receive Notices electronically by discontinuing your use of the Wiki Service.

==General Terms==

(a) This agreement constitutes the entire agreement between you and us concerning the subject matter of these Terms, which may only be modified by us. (b) This Agreement shall not be governed by the United Nations Convention on Contracts for the International Sale of Goods. (c) If any part of these Terms is held invalid or unenforceable, that part shall be construed to reflect the parties' original intent as nearly as practicable, and the remaining portions remain in full force and effect, or we may at its option instead terminate this Agreement. (d) English is the controlling language of these Terms. If you have received a translation into another language, it has been provided for your convenience only. (e) A waiver by either party of any term or condition of this Agreement or any breach thereof, in any one instance, shall not waive such term or condition or any subsequent breach thereof. (f) You may not assign or otherwise transfer by operation of law or otherwise this Agreement or any rights or obligations herein. We may assign these Terms to any entity, including to any of our affiliates or parent at our sole discretion. (g) These Terms shall be binding upon and shall inure to the benefit of the parties, their successors and permitted assigns.

Articles

2008-09-26T14:44:25Z

Tarik: /* Modern Skins */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

==Skin Articles==

===Classic Skins===
*Link to Classic Skin Article 1

===Modern Skins===
*[http://dev.aol.com/article/2007/winamp_skins Winamp Skins Development Tutorial]
*Link to Modern Skin Article 2
*[[Creating a ClassicPro Skin]]

===ClassicPro Skins===
* [[Creating a ClassicPro Skin]]

==Visualization Articles==
*[[MilkDrop_Preset_Authoring|MilkDrop Preset Authoring]]
*Link to vis Article 2

==Plug-in Articles==

*[[Wasabi|Overview of the Wasabi API]]
*[[Decode File API]]
*[[Media Library Plugin|How to create a Media Library plugin]]
*[[Input Plugin|How to create an Input plugin]]
*[[General Purpose Plugin|General Purpose plugins]]
*[[Output Plugin|How to create an Output plugin]]
*[[DSP Plugin|Audio Effects (DSP) plugins]]
*[[Random API]]
*[[Language API]]
*[[Agave Config API]]
*[[Album Art API]]
*[[Tagz API]]
*[[XML Parser Object]]
*[[System Callbacks API]]
*[[Skin API]]
*[[Service Manager API]]
*[[Memory Manager API]]
*[[Image Writer Service]]
*[[Image Loader Service]]
*[[Text Feed Service]]
*[[File Reader Service]]
*[[Application API]]
*[[Replay Gain API]]
*[[Podcasts API]]
*[[Agave Metadata API]]
*[[System Component Interface]]
*[[Burner API]]
*[[Audio Encoder Plugin|Audio encoders (transcoding, CD ripper)]]
*[[Skinning Plugins|WAC Skinning plugins]]
*[[Nullsoft Database Engine|Nullsoft Database Engine (NDE)]]
*[[JNetLib|JNetLib networking library]]
*[[APE Plugins|AVS Plugins]]
*[[NSV Plugins|NSV Audio and Video decoders]]
*[[Playlist API]]
*[[Media Core API|Media Core API (Freeform skins only!)]]
*[[SendMessage API|Winamp 2 API]]
*[[Media Library API|Media Library SendMessage API]]
*[[Plugin Terminology]]

==Web Development Articles==
* [[HTTP Example Plugin]]
* [[Javascript External Interface]]

Articles

2008-09-26T14:44:07Z

Tarik: /* Modern Skins */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

==Skin Articles==

===Classic Skins===
*Link to Classic Skin Article 1

===Modern Skins===
*[http://dev.aol.com/article/2007/winamp_skins Winamp Skins Development Tutorial]
*Link to Modern Skin Article 2
*[[Creating a ClassicPro Skin]]

===ClassicPro Skins===
* [[Creating a ClassicPro Skin]]

==Visualization Articles==
*[[MilkDrop_Preset_Authoring|MilkDrop Preset Authoring]]
*Link to vis Article 2

==Plug-in Articles==

*[[Wasabi|Overview of the Wasabi API]]
*[[Decode File API]]
*[[Media Library Plugin|How to create a Media Library plugin]]
*[[Input Plugin|How to create an Input plugin]]
*[[General Purpose Plugin|General Purpose plugins]]
*[[Output Plugin|How to create an Output plugin]]
*[[DSP Plugin|Audio Effects (DSP) plugins]]
*[[Random API]]
*[[Language API]]
*[[Agave Config API]]
*[[Album Art API]]
*[[Tagz API]]
*[[XML Parser Object]]
*[[System Callbacks API]]
*[[Skin API]]
*[[Service Manager API]]
*[[Memory Manager API]]
*[[Image Writer Service]]
*[[Image Loader Service]]
*[[Text Feed Service]]
*[[File Reader Service]]
*[[Application API]]
*[[Replay Gain API]]
*[[Podcasts API]]
*[[Agave Metadata API]]
*[[System Component Interface]]
*[[Burner API]]
*[[Audio Encoder Plugin|Audio encoders (transcoding, CD ripper)]]
*[[Skinning Plugins|WAC Skinning plugins]]
*[[Nullsoft Database Engine|Nullsoft Database Engine (NDE)]]
*[[JNetLib|JNetLib networking library]]
*[[APE Plugins|AVS Plugins]]
*[[NSV Plugins|NSV Audio and Video decoders]]
*[[Playlist API]]
*[[Media Core API|Media Core API (Freeform skins only!)]]
*[[SendMessage API|Winamp 2 API]]
*[[Media Library API|Media Library SendMessage API]]
*[[Plugin Terminology]]

==Web Development Articles==
* [[HTTP Example Plugin]]
* [[Javascript External Interface]]

Articles

2008-09-26T14:41:33Z

Tarik: /* Classic Skins */

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

==Skin Articles==

===Classic Skins===
*Link to Classic Skin Article 1

===Modern Skins===
*[http://dev.aol.com/article/2007/winamp_skins Winamp Skins Development Tutorial]
*Link to Modern Skin Article 2
*[[Creating a ClassicPro Skin]]

==Visualization Articles==
*[[MilkDrop_Preset_Authoring|MilkDrop Preset Authoring]]
*Link to vis Article 2

==Plug-in Articles==

*[[Wasabi|Overview of the Wasabi API]]
*[[Decode File API]]
*[[Media Library Plugin|How to create a Media Library plugin]]
*[[Input Plugin|How to create an Input plugin]]
*[[General Purpose Plugin|General Purpose plugins]]
*[[Output Plugin|How to create an Output plugin]]
*[[DSP Plugin|Audio Effects (DSP) plugins]]
*[[Random API]]
*[[Language API]]
*[[Agave Config API]]
*[[Album Art API]]
*[[Tagz API]]
*[[XML Parser Object]]
*[[System Callbacks API]]
*[[Skin API]]
*[[Service Manager API]]
*[[Memory Manager API]]
*[[Image Writer Service]]
*[[Image Loader Service]]
*[[Text Feed Service]]
*[[File Reader Service]]
*[[Application API]]
*[[Replay Gain API]]
*[[Podcasts API]]
*[[Agave Metadata API]]
*[[System Component Interface]]
*[[Burner API]]
*[[Audio Encoder Plugin|Audio encoders (transcoding, CD ripper)]]
*[[Skinning Plugins|WAC Skinning plugins]]
*[[Nullsoft Database Engine|Nullsoft Database Engine (NDE)]]
*[[JNetLib|JNetLib networking library]]
*[[APE Plugins|AVS Plugins]]
*[[NSV Plugins|NSV Audio and Video decoders]]
*[[Playlist API]]
*[[Media Core API|Media Core API (Freeform skins only!)]]
*[[SendMessage API|Winamp 2 API]]
*[[Media Library API|Media Library SendMessage API]]
*[[Plugin Terminology]]

==Web Development Articles==
* [[HTTP Example Plugin]]
* [[Javascript External Interface]]

Tagz API

2008-09-25T13:13:33Z

Tarik: Protected "Tagz API" [edit=autoconfirmed:move=autoconfirmed]

Tagz is the title formatting engine that powers the playlist titles. (See Winamp preferences->Titles->Advanced Title Formatting for more information). You can use this title formatting engine for your plugin's needs, optionally providing your own metadata for %artist%, etc.

Note that although Winamp's Tagz engine and the Tagz engine in Foobar2000 both come from a common source, they have diverged significantly and are not compatible for anything but the simplest of formats.

Interface: api_tagz

Include file: tagz/api_tagz.h

You can also use Tagz via [[SendMessage API|WM_WA_IPC]]:

#define IPC_FORMAT_TITLE 297
#define IPC_FORMAT_TITLE_EXTENDED 298

Subclassing

2008-09-25T13:13:28Z

Tarik: Protected "Subclassing" [edit=autoconfirmed:move=autoconfirmed]

== Subclassing ==

Subclassing is a technique common to Windows development. It involves supplying your own window function for someone's window, and changing behavior by supplying your own logic for processing certain messages.

Because your plugin is given Winamp's HWND during initialization, it is possible for your plugin to subclass Winamp's main window. Since the [[SendMessageAPI|Send Message API]] is built by sending messages to the Winamp window, your plugin can do a great deal without even effecting the UI. From simple notifications (e.g. Winamp sends msg=WM_WA_IPC, wParam=IPC_CB_MISC_TITLE, lParam=IPC_CB_MISC on song change) to radically altering behavior (e.g. Winamp checks the return value of msg=WM_WA_IPC, lParam=IPC_GET_NEXT_PLITEM to allow plugin's to override playlist playback order).

Service Manager API

2008-09-25T13:13:23Z

Tarik: Protected "Service Manager API" [edit=autoconfirmed:move=autoconfirmed]

api/service/api_service.h

Random API

2008-09-25T13:13:12Z

Tarik: Protected "Random API" [edit=autoconfirmed:move=autoconfirmed]

Agave/Random/api_random.h

Nullsoft Database Engine

2008-09-25T13:12:04Z

Tarik: Protected "Nullsoft Database Engine" [edit=autoconfirmed:move=autoconfirmed]

The Nullsoft Database Engine powers the local media library, history, and the CD metadata database. It is relative simple and has a small query language.

Modern Skin: Snap Points

2008-09-25T13:11:55Z

Tarik: Protected "Modern Skin: Snap Points" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Simple Skin Tutorial

2008-09-25T13:11:49Z

Tarik: Protected "Modern Skin: Simple Skin Tutorial" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Maki Overview

2008-09-25T13:11:33Z

Tarik: Protected "Modern Skin: Maki Overview" [edit=autoconfirmed:move=autoconfirmed]

Creating a Modern Skin --> [[Modern Skin: Intro|Intro]] --> [[Modern Skin: Winamp 2 to W3+|Winamp 2 to Winamp 3+]] --> [[Modern Skin: Simple Skin Tutorial|Simple Skin Tutorial]] --> [[Modern Skin: XML Intro|XML Intro]] --> [[Modern Skin: Simple Skin Tutorial (Continued)|Simple Skin Tutorial (Continued)]] --> [[Modern Skin: Container| Container]] --> [[Modern Skin: Group|Group]] --> [[Modern Skin: Relative Positioning| Relative Positioning]] --> [[Modern Skin: Complex Skin|Complex Skin]] --> [[Modern Skin: Non-Rect Player| Non-Rect Player]] --> [[Modern Skin: Layer Composition| Layer Composition]] --> [[Modern Skin: Alpha Channels| Alpha Channels]] --> [[Modern Skin: Animatedlayer|Animatedlayer]] --> [[Modern Skin: Snap Points|Snap Points]] --> [[Modern Skin: Drawers|Drawers]] --> [[Modern Skin: Skin Scripting| Skin Scripting]] --> [[Modern Skin: Drawer Scripting| Drawer Scripting]] --> [[Modern Skin: Animating a Skin|Animating a Skin]] --> [[Modern Skin: Maki Overview| Maki Overview]] --> [[Main_Page#Glossary_of_Terms|Glossary]]

==What is Maki==

Maki is a user interface and event management scripting system and more. The primary purpose of Maki is to handle all of the user interface behavior. Maki is used to insert functionality in Winamp3. The inserted functionality can range from a new user interface behavior to an alarm clock to a seperate EQ control system. You must not forget that Maki is part of Wasabi, which is used to build Winamp3. It's therefor safe to assume that Wasabi based applications (other than Winamp3) support Maki also. Well, when there are others that is.

==What does Maki mean?==

'''M'''ake '''A''' '''K'''iller '''I'''nterface

==What can Maki do?==

Maki as a language can do pretty much everything most scripting languages do. It supports user functions, user classes. It also has a full fledged pre-processor that allows you to include other Maki source files. Maki scripts are actually compiled using the Maki Compiler (MC.EXE, look for it in your Winamp3 directory. Don't worry about the compiler, we'll explain how it works later on).

So here's a list of what Maki can do, just remember, it might change, but always in a good way, at least, we hope so.

*Trap and hook events (onClick() do something...)
*Move user interface elements (take button A and move it to position x,y)
*Move and change images (button A has image A, set button A's image to image B)
*Show and Hide Windows.
*Control Winamp3 playback (play, stop, next, etc.)
*Control Winamp3 volume (set the volume to 100%)
*Control Winamp3 equalizer levels (set 60hz to +20db, for you bass addicts.)
*Make an Alarm
*Make a Clock
*etc.

Now, you might not realise it, but the fact it can trap events and hook events and create new GUI objects on the fly means it can pretty much do anything. Something very important to remember is that some GUI objects need to be "binded" before being able to be used to trap events. The best way to go about this is to remember that objects need to be binded before being used. Here's a short example:

Global Timer myTimer;
System.onScriptLoaded() {
myTimer = new Timer;
}
myTimer.onTimer() {
//Do cool stuff here.
}

==When should I use Maki?==

It's always hard to decide if you want to implement something via scripting or component. Always remember that many things can be done with Maki and that implementing something via scripting is also much faster than using a component. This is super true when it comes to user interface behavior in skins. Literaly ANYTHING that has to do with how the user interface (skin) behaves and changes because of user input is pretty darn quick to write in scripting, but you can still do it in a component if you wish.

Mainly, you have to look at the potential level of complexity of what you're trying to do. You don't want to implement something very complex in script because it will definitely be slower than straight C++ code.

==Maki Syntax==

Here's where the fun ends for me and I have to start being all serious and actually explain important stuff. Ugh. So, first I'm going to explain general syntax, like what constitutes an instruction, how you terminate lines, etc. Then we'll jump into variables, functions, classes and class members. Here we gooooooooo!

First off, Maki is NOT case sensitive, so a function named llama can also be called by using Llama. I'd also like to point out the difference between pre-processor statements and actual code statement. Pre-processor statements are read and processed FIRST, before even ONE shred of code is actually compiled. They start with # and end with a carriage return. Actual code starts pretty much with anything but # and ends with a ;. This excludes flow control statements (like if(..) {... ). Now I know it's a bit odd to just read things and not see it, so, how about a little example? *nod*

First, pre-processor statements:

#include "../../lib/std.mi"

#define ACTIVEALPHA (230)
#define INACTIVEALPHA (150)

The pre-processor statements are pretty self explainatory. I'll explain what they actually mean really soon, just observe the syntax for now.

Now, a code snippet:

if (isactive != prev_active) {
prev_active = isactive;
fader.start();
}

Since if is a control statement and marks the beginning of a code block ( a code block is something in between { .. } ), it doesn't require a ;, the line below it however, isn't a control statement and requires the line to end with a ;. Again, I will explain what everything means later, for now, just observe the syntax.

==Maki Datatypes==

In this section, we'll go thru all the different datatypes available in Maki and how to use them (And also, a quick overview of what exactly is a variable in Maki). Currently in Maki there are 6 basic types you can use:

*Boolean
*Int
*Float
*Double
*String
*Object<nowiki>*</nowiki>

<nowiki>*</nowiki> Object is a compound type, we'll see what it means later.

Now for a description of each of the types. Please note that the variable types aren't case sensitive.

===Boolean===

Boolean is a boolean value that can have two states. For us, these states are true (1) and false (0). Here's how you create a Boolean variable and assign a value to it:

//Create a bool type variable and assign 0 (false) to it.
Boolean state = 0;

//Assign 1 (true) to our bool variable named state.
state = 1;

//Assign false (0) to our bool variable named state.
state = false;

//Assign true (1) to our bool variable named state.
state = true;

===Int===

Int is a signed* round integer value from -2 147 483 647 to +2 147 483 648 (this means no decimal values, ever). Here's how you create an Int variable and assign a value to it:

//Create an int type variable and assign 255 to it.
Int alpha = 255;

//Assign the value 1000 to our int variable named alpha.
alpha = 1000;

//Assign the value -1000 to our int variable named alpha.
alpha = -1000;

===Float===

Float is a signed floating point number. Here's how you create a Float variable and assign a value to it:

//Create a float type variable and assign 0.25 to it.
Float fraction = 0.25;

//Assign the value 0.5 to our float variable named fraction.
fraction = 0.5;

//Assign the value -3.5566 to our float variable named fraction.
fraction = -3.5566;

===Double===

Double is a signed floating point number with double precision.

//Create a float type variable and assign 0.000000125 to it.
Double fraction = 0.000000125;

//Assign the value 0.5 to our double variable named fraction.
fraction = 0.5;

//Assign the value -3.5566 to our double variable named fraction.
fraction = -3.5566;

===String===

String is a string, it can be of any length. Here's how you create a String variable and assign a value to it:

//Create a string type variable and assign a sentence to it.
String name = "My real name is not Aus.";

//Assign the value "Guru" to our string variable named name.
name = "Guru";

//Assign the value "Francis" to our string variable named name.
name = "Francis";

===Object===

Object is a compound type. This means it can have more than just one value associated with it. Infact, you can even attach values to it, and even other objects.

===Null===

Null is a special case. You can't create a variable of this type, it is ONLY used in comparaisons and can compare to any type variable and object. You can use it to see if a variable contains something or exists.

==Maki Operators==

===Mathematical===

All basic math operators are available, here's a list of them and what they do.

[[Image:Table1.png]]

===Logical===

[[Image:Table2.png]]

===Bit===

[[Image:Table1.png]]

===Assignment===

[[Image:Table1.png]]

==Maki Control Structures==

Control structures are what influence the flow of the code, certain parts are executed only in certain cases, some a fixed amount of times, some a variable amount of times, etc. Most of the basic control structures found in modern languages are available in Maki. Here's a list of them:

===if===

if(state == true) {
state = false;
}

===if else===

if(state == true) {
state = false;
} else {
state = true;
}

===while loop===

while(state == true) {
...
}

===do while loop===

do {
...
} while(state == true);

===for loop===

for(int i = 0; i < 10; i++) {
...
}

==Maki Functions==

===How do I create my own Maki functions===

Functions in Maki need to be declared before they can be used (you can declare and define it if you want also). When declaring a function you need to use the proper prototype line for the function you wish to create. This includes the return value type and the parameters it takes.

There are two ways you can go about creating functions.

1) You can group all your function declarations (called prototypes) at the top of your script and then define (write the actual code associated with the functions) them anywhere in the file. Like so:

#include

Function Boolean CheckLevel(int Threshold);
Function Int CheckPlaystring(String _Playstring);

...

Boolean CheckLevel(int Threshold) {
...
}

Int CheckPlaystring(String _Playstring) {
...
}

2) You can declare the function just before defining it. Like so:

#include
...
Function Boolean CheckLevel(int Threshold);
Boolean CheckLevel(int Threshold) {
...
}

The preferred method is the first because it's just much easier to organize things, but, you can do it the other way if you want to.

===How to read function prototypes===

Function RETURN_VALUE_TYPE FUNCTION_NAME(PARAM_TYPE PARAM_NAME, ...);

*RETURN_VALUE_TYPE is the type of the return value, it can be any type supported by Maki, including user classes.
*FUNCTION_NAME is the name of the function you are declaring. It can be any combination of letters and numbers but it MUST start with a letter.
*PARAM_TYPE is the type of the parameter you will be passing to the function, it can be any type supported by Maki, including user classes.
*PARAM_NAME is the name the parameter will have inside the function, it can be any combination of letters and numbers but it MUST start with a letter.

The function's name and parameter names CAN NOT use any of the existing Maki keywords.

==Maki Classes==

The already existing Maki classes usually consist of two things: member data and methods. It's very important to remember that user classes do not support methods yet. (needs improvement)

==Maki User Classes==

(needs improvement)

==Gerneral Scripting Rules==

These are just general things you want to keep in mind when writing Maki scripts and when writing code in general too! :)

*As a rule of thumb, all uppercase is reserved for constants. So please avoid naming anything that's not a constant all in uppercase.

==STD.MI Reference==

If you'd like to know more about STD.MI simply open it in your favorite text editor and check out the spiffy comments. If you need more help, [http://forums.winamp.com/ check out the forums!]

Modern Skin: Group

2008-09-25T13:11:25Z

Tarik: Protected "Modern Skin: Group" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Container

2008-09-25T13:11:19Z

Tarik: Protected "Modern Skin: Container" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Animatedlayer

2008-09-25T13:11:13Z

Tarik: Protected "Modern Skin: Animatedlayer" [edit=autoconfirmed:move=autoconfirmed]

MilkDrop Unleashed Guide

2008-09-25T13:11:08Z

Tarik: Protected "MilkDrop Unleashed Guide" [edit=autoconfirmed:move=autoconfirmed]

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

===Installation===
MilkDrop 2 comes with Winamp. To install it, just download and install the latest version of Winamp. During the installation, make sure the "MilkDrop" visualizer option is checked, so that it gets installed, too.

Once Winamp is installed, launch it. Load some music files into your playlist and start playing some music. (Be sure to play some music before trying to launch the visualizer - otherwise you'll just see a black screen.)

Once music is playing, hit CTRL+K and a list of visualization plug-ins will appear. Select "MilkDrop 2" from the list. Then click the "Start" button, and it will launch the visualizer.

Quick Tips:
* If you want to go full-screen, double-click on the visualizer itself.
* CTRL+SHIFT+K starts or stops the visualizer.
* To configure MilkDrop's options, exit the visualizer and hit ALT+K.

If you have trouble getting MilkDrop to run properly after installation,
try installing various recent WHQL drivers for your video card, or installing
DirectX; doing these two things (especially the first) will fix 99% of
problems. See the Troubleshooting section of the documentation for more
information.

===Tweaking to achieve best image quality===

a) Fullscreen Display Mode [first tab of config screen]

When you run MilkDrop fullscreen, it changes the display mode to whatever you select here. Generally speaking, the speed (framerate) and smoothness of MilkDrop will drop as the resolution (number of pixels on the screen)increases. So, if it's running to slow in fullscreen mode, try selecting a smaller fullscreen display mode.

b) Canvas Stretch [second tab]

This option lets you trade resolution [crispness] for speed. If MilkDrop runs too slow, in any mode (windowed/fullscreen/desktop), try cranking up the canvas stretch to, say, 1.5X or 2X. The image will not look as crisp, but MilkDrop will probably run much faster. (Assuming that your graphics chip was the bottleneck.)

c) Mesh Size [second tab]

This is the main option that affects how much processor (CPU) MilkDrop uses. If you crank it up far beyond the default, expect to be CPU-bound (where your framerate drops because the CPU is the bottleneck). To get MilkDrop to speed up, drop the Mesh Size back down. The Mesh Size decides how many points on the screen the per-vertex equations will be executed for; the higher the mesh size, the more fidelity you will see in the motion.

d) Tips for LCD and laptop users

LCD screens: Note that most LCD screens (flatpanels) usually run at a fixed frequency only - usually 60 Hz - meaning that they update the screen 60 times per second. However, sometimes the video driver reports that it supports other refresh rates, such as 72, 75, 85, etc. It is strongly recommended that [for fullscreen mode, and for Windows in general] you choose a display mode with a 60 Hz refresh rate, for the smoothest possible animation. For this plugin, you will also want to choose Maximum Framerates that divide evenly into 60 - such as 60, 30, 20, 15, 12, 10, 6, 5, and so on - so that the # of times the LCD shows each frame of animation remains constant, resulting in the smoothest possible animation.

e) color (bit) depth: 16 or 32?

The answer, nowadays, is a resounding "32". Video memory is plentiful these days; use 32 bit color, for both your windows desktop (...so that MilkDrop's windowed mode can run at 32 bits) and for MilkDrop's Fullscreen Display Mode setting (where "8888" denotes 32 bits). Some ancient video cards don't have enough memory to run MilkDrop properly (or smoothly) in 32 bits, though; you might want to try 16-bit color if your card has less than 32 MB of video memory, if you are using a laptop, or if your video card is significantly old. In the MilkDrop config panel, 16-bit modes show up as "555" or "565".

If you find that your card runs best in 32-bit color, you should have no problems with brightness levels while running MilkDrop. However, if your card runs best in 16-bit color, you should then adjust the Brightness slider on the second tab of the config panel (which only affects 16-bit color video modes!). The goal is to make the image as bright as possible, without oversaturating it (washing it out, often to bright pink or white). This setting also varies for different cards, depending on how the card rounds color values, so we recommend seeing how bright you can set the slider closer to '0') without oversaturating the image. Usually,a setting of '0' or '2' works the best.

===Usage===

'''4.a. Keyboard Commands'''

The following keys can be used to control MilkDrop while it is running.
(Note: pressing F1 while MilkDrop is running will show you this list)

GENERAL
escape: exit to winamp
PRESET LOADING
BACKSPACE: return to previous preset
SPACE: transition to next preset
H: instant Hard cut (to next preset)
R: toggle random (vs. sequential) preset traversal
L: load a specific preset (invokes the 'Load' menu)
+/-: rate current preset (better/worse)
scroll lock: lock/unlock current preset
(keyboard light on means preset is locked)
(prevents random switch to new preset)
A: aggregate preset - loads a random preset,
steals the warp shader from a different random preset,
and steals the composite shader from a third random preset.
D: cycle between various lock-states for the warp and
composite shaders. When one of these shaders is locked,
loading a new preset will load everything *except* the
locked shaders, creating a mix between the two presets.

PRESET EDITING AND SAVING
M: show/hide the preset-editing menu
S: save new preset (asks you for the new filename)
N: show per-frame variable moNitor
(see [[MilkDrop Preset Authoring]])

MUSIC PLAYBACK
z/x/c/v/b: navigate playlist (prev/play/pause/stop/next)
U: toggle shuffle
P: show playlist
up/down arrows: volume up/down
left/right arrows: rewind/ffwd 5 seconds
SHIFT + left/right arrows: rewind/ffwd 30 seconds

FUNCTION KEYS
F1: show help screen
F2: show song title
F3: show song length
F4: show preset name
F5: show fps (frames per second)
F6: show rating of current preset
F7: re-read custom message file (milk_msg.ini) from disk
F8: jump to new directory (for presets)
F9: toggle stereo 3D on/off

SPRITES AND CUSTOM MESSAGES (FOR VJ's)
T: launch song title animation
Y: enter custom message mode
##: load message ## (where ## is a 2-digit numeric code (00-99)
of a message defined in milk_msg.ini)
*: clear any digits entered.
DELETE: clear message (if visible)
F7: re-read milk_msg.ini from disk
K: enter sprite mode
##: load sprite ## (where ## is a 2-digit numeric code (00-99)
of a sprite defined in milk_img.ini)
*: clear any digits entered.
DELETE: clear newest sprite
SHIFT + DELETE: clear oldest sprite
CTRL+SHIFT+DELETE: clear all sprites
F7: no effect (milk_img.ini is never cached)
SHIFT + K: enter sprite kill mode
##: clear all sprites with code ##
*: clear any digits entered.
CTRL + T/Y: kill song title and/or any custom messages
CTRL + K: kill all sprites

Note that there are more keys available, but because many
are only relevant to people designing their own presets,
they are listed in the preset authoring guide instead.

'''4.b. config panel'''

The configuration panel lets you customize the way MilkDrop runs.
To learn how to get to the configuration panel, see the "Installation"
section above.

Once you're in the config panel, you'll see a number of tabs
at the top, some dropdown boxes, and some checkboxes. Each
of the tabs at the top brings you to a different page of
configuration options. To get help on a setting, simply click
on the '?' in the upper-right corner of the config panel,
and then click on the setting you want help with.

'''4.c. preset authoring'''

Please check the [[MilkDrop Preset Authoring]] guide for instructions on how to create and save your own presets.

'''4.d. rating system'''

The built-in rating system allows you to rate each preset on a scale
from 0 to 5. A rating of 5 is very good, while a rating of 0 is
the worst. The ratings decide how often the presets will be randomly
loaded. If a preset has a rating of 0, it will never be randomly
loaded (unless they're all zero; then they all have an equal chance).

To show the rating for a preset, press F6. You can adjust the
rating for a preset with the +/- keys. When you make adjustments,
they save automatically; there's no need to save the preset to make
the rating change permanent.

Here's a recommended interpretation of the numeric values:
0 = I never want to see this preset again
1 = very ugly
2 = mediocre
3 = fair
4 = good
5 = downright stimulating

If a preset seems "lost" because you set its rating to 0 and it
won't ever come back, you can always load it up by hitting 'L'
to conjure the 'Load Preset' menu, finding the preset you want,
loading it, then hitting +.

'''4.e. custom messages'''

ABOUT CUSTOM MESSAGES:
The "Custom Message" feature of MilkDrop allows you to display
short text messages on the screen while MilkDrop is running.
They are highly configurable; you can set all of the following
parameters: the font, the size, the positioning, color, bold
state, italic state, and so on; and you can even have it
randomize some of these properties.

CREATING THE MESSAGES:
You can save up to 100 messages in the file MILK_MSG.INI in
your Winamp\Plugins\ folder. To open this file, go to the
MilkDrop configuration screen (ALT+K from Winamp) and click the
"Edit Custom Messages" button. Or, you can just edit it
manually if you know how; it's plain-text.

The first thing you see when you open the file is a bunch of
lines that start with two forward slashes (//). These are
comment lines, and they explain the syntax for adding a font
or a message to the file. This is your main reference for
finding out what all the parameters do for the fonts & messages;
it is recommended that you leave this information in the file,
although it can be removed or (modified) and the messages will
still work.

After the comments come first the fonts, then the messages.
The fonts are simply a way to specify a typeface, bold state,
italics state, and red/green/blue color for the font. You can
configure up to 16 fonts like this (numbered 00-15). These fonts
will serve as template fonts for the custom messages.

The next section is the actual messages. Each one has a
text message (the 'text' parameter) that will be shown to the
user, and each one references one of the 16 fonts that were
defined in the previous section. You can also specify the
size (size), position (x,y), a growth factor (growth) that
will grow/shrink the message over its lifetime, the number
of seconds to show the message (time), and the fraction of that
time that is spent fading in (fade).

You can also randomize some of these values: 'randx' and 'randy'
will randomly perturb the (x,y) coordinates every time the message
is shown to the user, and 'randr'/'randg'/'randb' will randomly
perturb the (r,g,b) color in the same way.

Finally, you can override any of the default properties for the
font that this message uses: (face, bold, ital, r, g, b).

INVOCATION AND USAGE:
There are two ways to invoke custom messages: one automatic,
the other manual.

The automatic way is to go to the MilkDrop config panel (ALT+K),
click the 'More Options' button, and set the value in the
'Time between RANDOM custom messages' box to something greater
than zero. This will cause MilkDrop to randomly display custom
messages while it is running, and the average time (in seconds)
between messages will be the value you entered here. If you
wish to disable random custom messages, set this value to -1
(or any negative number). Note that all messages in the file
have an equal change of being picked.

The manual way is to type in the two-digit code (00-99) of the
message while MilkDrop is running. However, you can't use the
numeric keypad for this - you have to use the numbers at the
TOP of your keyboard to do it. If you mess up while entering
the first digit, just press the '*' key to start over.

Note that if you change the MILK_MSG.INI file while MilkDrop
is running, you will not be able to see the changes until
you hit F7, which tells MilkDrop to re-read the MILK_MSG.INI
file from disk.

'''4.f. sprites'''

ABOUT SPRITES:
The "Sprite" feature of MilkDrop allows you to display any image of your choice in the foreground (on top of MilkDrop) while it runs. The sprites can fade in and out, move around, respond to the music, and so on. You define them in a file - milk_img.ini in your winamp\plugins directory - much like you define custom messages, each having an identifying code number from 00 through 99 (used to invoke them). However, the way the individual sprites are defined is different; you write code for them, instead of just setting parameter values. This is a little bit tougher to do (it's very much like preset authoring), but adds a great deal of flexibility to what you can do with the sprites.

CREATING THE SPRITES:

You can define up to 100 sprites in the file MILK_IMG.INI in your Winamp\Plugins\ folder. To open this file, go to the MilkDrop configuration screen (ALT+K from Winamp) and click the "Edit Sprites" button. Or, you can just edit it manually if you know how; it's plain-text.

The first thing you see when you open the file is a bunch of lines that start with two forward slashes (//). These are comment lines, and they explain the syntax for creating a sprite. This is your main reference for finding out what all the parameters do for the fonts & messages; it is recommended that you leave this information in the file, although it can be removed (or modified) and the sprites will still work.

After the comments come the sprite definitions. Each sprite is made up of one parameter that indicates the image file to use (this is the 'img=...' line), and two types of code: initialization code, and regular code.

The first - initialization code - is executed only once, when you launch the sprite. Use it to do one-time initialization of variables (such as the opacity (a), rotation angle (rot), position (x,y), and so on) or to invent new variables that you will access later. This code is marked by the 'init_1=...', 'init_2=...', etc. lines. The second type of code - marked by 'code_1=...', 'code_2=...', etc. is executed every frame, just prior to plastering the sprite on the screen. Use it to animate the sprite, moving it around (changing x,y), scaling it up and down (sx,sy), fading it in and out (a), changing its color, and so on.

Please see the comments included in the sample milk_img.ini file
for full details and examples on how to author sprites.

INVOCATION AND USAGE:
There is currently only one way to invoke sprites: manually. To do this, first press 'K' to enter 'sprite mode' (while running MilkDrop). Now, whenever you type in a two-digit code (00-99), MilkDrop will try to find & launch the sprite you've requested, from the milk_img.ini file. If there is an error, it will display an error message in the upper-right corner. Note that to enter the two-digit code, you can't use the numeric keypad; you have to use the numbers at the TOP of your keyboard.

If you make an error entering the first digit of the code, just press '*' to start over. If you want to clear the most recently-invoked sprite, press DELETE. If you want to clear the oldest sprite, press SHIFT + DELETE. If you want to clear all sprites, press SHIFT + CTRL + DELETE.

If you want to clear sprites by their 2-digit code, press SHIFT + K (instead of just 'K') to enter 'sprite kill mode.' Now, when you enter a two-digit code, instead of invoking the sprite, MilkDrop clears all running sprites with that two-digit code.

===Trouble Shooting===

If MilkDrop has a critical problem (e.g. fails to load, freezes, etc.)or if the image is distorted, torn, corrupted, or all one solid color, try the following two suggestions to resolve the problem. In 90% of these cases it can be fixed. If you have a different problem, scroll down past this part and try to find the appropriate symptom and its solution.

====1. UPDATE YOUR VIDEO DRIVER, OR TRY OTHER DRIVERS====

Almost all display problems are caused by buggy video drivers! A "driver" is a piece of software that translates graphics-related commands from programs, like MilkDrop, into the native language of your specific graphics hardware.

For desktop machines, there are typically three sources for video drivers:
# those from the *chip* manufacturer's website (usually nvidia.com or ati.com) (best source)
# those from the card manufacturer's website (LeadTEK, PNY, etc.)
# those that shipped with Windows (yuck)

For laptops:
# the driver from the *laptop* manufacturer
# (maybe) the driver from the graphics chip manufacturer (ATI, Nvidia, etc) - however, it's fairly common to find that the laptop requires a custom driver written by the laptop manufacturer.
# the driver that shipped with Windows (yuck)

Give them all a shot. Track down every driver you can find for your card, and try it. Try the WHQL ones first - these versions of the drivers have passed "Windows Hardware Quality Labs" certification and are usually the more stable and reliable ones. In general, it's a very good idea to use only Microsoft-certified WHQL drivers for your video card. Often people want to get the newest, fastest beta drivers, but these drivers are almost ALWAYS riddled with new bugs. You can also watch the version number of the drivers a company releases - if the version number just jumped to a new series such as from the 70's to the 80's), watch out, it probably has a lot of bugs that need worked out - give it 3-4 months before expecting the new driver series to work well. With video drivers, the newest isn't always the best!

Here is a list of some common card/chip manufacturers and where to get their drivers. Don't forget to choose the WHQL driver!

[http://www.nvidia.com/page/drivers.html NVIDIA driver]
Card manufacturers using NVIDIA (GeForce) graphics chips:
(note - most of these just link you to the nvidia driver above)
[http://www.xfxforce.com/web/support/showSearchDriversProductCode.jspa XFX]
[http://www.evga.com/support/drivers EVGA]
[http://www.bfgtech.com/driverdownload.aspx BFG]
[http://www2.pny.com/support/support.aspx PNY]
[http://ati.amd.com/support/driver.html ATI driver]
Card manufacturers using ATI (Radeon) graphics chips:
[http://www.visiontek.com/teksupport/drivers/drivers.html VisionTek]
[http://www.dmmdownload.com/current.php Diamond]
[http://downloadcenter.intel.com Intel] - then click 'graphics' on the left
[http://www.sis.com/download SiS] - agree, then select 'graphics drivers'
[http://www.s3graphics.com S3] - then click 'drivers'
[http://www.via.com.tw/en/products/graphics VIA]
[http://www.matrox.com/graphics/en/corpo/support/drivers/home.php Matrox]
[http://www.creative.com/language.asp?sDestUrl=/support/downloads Creative Labs]

For others - or in general - if your graphics chip is made by Trident, for example, then try a [http://www.google.com/ google] search for:

Trident graphics driver

Then click on "support", then "drivers" (or "downloads"), then "graphics driver", and so on.

====2. [RE]INSTALL DIRECTX====

Make sure you have a quasi-recent version of Microsoft DirectX installed. In reality, though, almost every PC in the world has DirectX 9 on it at this point, so this shouldn't be a problem. If you go to download it, you'll only be able to find DirectX 10 - this is fine to install, though, as it includes DirectX 9 inside it. As a last resort, though, if you are having problems, you could try re-installing DirectX to see if it helps.

If you're having a non-critical problem, browse the following list of common problems and their causes and solutions. Note that for each symptom- cause-solution block, there can be multiple symptoms with the same cause and solution, and the same symptom might be listed in multiple blocks.

If the solutions below don't work for you, please visit the forums at http://forums.winamp.com/forumdisplay.php?forumid=84, where you can read the most recent troubleshooting issues and solutions.

ENTRY 1
SYMPTOM:
-any error message saying "Failed to create ..."
or "not enough memory...", or
-only a portion of the screen displays correctly; the rest is
either filled with garbage or badly flickering
CAUSE:
1) Your video card might not have enough memory to run MilkDrop at
the resolution (screen width and height) you've picked,
2) your drivers might be out of date,
3) you might need to reinstall DirectX (very very rare), or
4) your graphics card might be to crappy to *actually* run
pixel shaders well.
SOLUTION:
1) To battle video memory problems:

Go to the config panel and try smaller video modes (e.g.,
320x240 is smaller than 640x480). Even better is to try
a lower color bit depth; if you'd selected a 32-bit ("8888")
video mode before, try a 16- ("565" or "555") or 24-bit ("888")
one, for example. Note that it might only work in one of them;
so make sure you try them all. Trying these things is especially
important on laptops with limited video memory, or older video
cards with a small amount of video memory.

Finally, you can try locking the texture size (or "canvas size")
to 256x256 pixels, just to see if that fixes the problem.
If it does, try using a smaller fullscreen video mode to
free up some memory, or if running windowed, close other
graphics-hungry applications.

2,3) for instructions on how to reinstall DirectX or update
drivers, go here.

4) Go to the MilkDrop config panel (hit ALT+K) and on the second tab,
in the "Pixel Shaders" box, select "None." Now does MilkDrop run
ok? If so, your video card probably just can't reliably run
pixel shaders, due to either inferior hardware, or it could
be the driver. You can always try setting "Pixel Shaders"
back to "Auto" and then installing a newer (preferably WHQL)
video driver.

ENTRY 2
SYMPTOM:
-When I go to the Load Preset menu ('L') in MilkDrop, some of the
presets on disk are missing.
-I downloaded some new presets and put them in my Plugins\MilkDrop2\Presets
directory, but I can't access them from within MilkDrop.
CAUSE:
You probably have an older video card that can't handle the pixel
shaders needed to run some of the presets. MilkDrop automatically
hides any presets from you that you can't run.
SOLUTION:
* You could buy a new graphics card - one that meets the minimum
recommendation for MilkDrop 2. These cost less than $40.
* You could try forcing MilkDrop to try to run these presets.
Sometimes MilkDrop just hides them from you because it predicts
they will run horribly slow on your graphics card; in case it
is wrong about that, try this. Go into the MilkDrop config
panel (ALT+K) and go to the More Settings tab. Under the
"Pixel Shaders" option, change it from "Auto" to "Shader Model 2"
or "Shader Model 3". Then try to run MilkDrop and see if the
presets appear. If they do, you're in luck; if they don't, your
GPU really doesn't support those shader models.

ENTRY 3
SYMPTOM:
MilkDrop always looks the same - it's always showing the same
preset, and it never changes to a new preset unless I tell it to.
CAUSE:
Scroll Lock is on.
SOLUTION:
The Scroll Lock key is how you tell MilkDrop to lock the current
preset - i.e. don't randomly transition to a new preset unless you
do it. The state of the Scroll Lock key is remembered when you
start or stop MilkDrop, too, so be careful of that. If you are
experiencing this problem, you can fix it in any of the following
three ways:
1. hit Scroll Lock while MilkDrop is running (and the viz window is active);
2. load up the MilkDrop config panel (ALT+K), go to the More Settings
tab, and uncheck the "Start milkdrop with preset lock (scroll lock)
key ON" box;
3. if you're using a modern skin, there is a "random" button on
the frame of the window, which is the inverse of the Scroll Lock
state - i.e. you probably have Scroll Lock on and "random" off.
Click the "Random" button to turn random transitions back on
(and notice that scroll lock gets turned off as a result).

ENTRY 4
SYMPTOM:
I was browsing for presets from within MilkDrop ('L') key and
got lost. How do I get back to my presets?
SOLUTION:
Two ways to fix this. The easiest is to just reset MilkDrop
to its defaults - hit ALT+K to load the MilkDrop config panel,
then click the 'Defaults' button. The next time you launch
MilkDrop, it will start you in the default preset directory.

To fix it manually (and preserve all your settings), run
MilkDrop, hit F8, and paste in this path:
C:\Program Files\Winamp\Plugins\Milkdrop2\presets
[or equivalent].

Another way to fix it is to hit 'L', and browse all the way
down to the root folder (repeatedly select ".."), then
go into Program Files, Winamp, Plugins, MilkDrop2, and finally,
presets.

ENTRY 5
SYMPTOM:
-things flicker through (such as my AIM window ticker, taskbar
clock, web page animations, etc.) when I'm running MilkDrop
in fullscreen mode.
CAUSE:
You're probably running MilkDrop fullscreen at the same
resolution & color depth as your desktop, and Windows isn't
properly handling MilkDrop's request for exclusive access to the
screen, and is still letting other applications paint (draw)
themselves.
SOLUTION:
Change either your Windows desktop resolution or color depth, or
MilkDrop's fullscreen resolution or color depth, so that there
is some difference between the two. (To change your Windows
display settings, go to the Start Menu -> Settings -> Control
Panel -> Display -> Settings tab, and then change the "colors"
or "screen area" settings from there.) Also make sure you're
not using "fake" fullscreen mode (...uncheck this box on the
main screen of the config panel).

===Known Issues / Misc. / Tips:===

a. Tip for video capture: if you'd like to save sequences of video
from this plugin, there are several programs out there that will
let you do this. Warning: you will need a ton of free hard drive
space, and a fast CPU helps. A few of these programs are:
"FRAPS" http://www.fraps.com/
"Hypercam" http://www.hyperionics.com

b. Close other apps:
For the best graphics performance, try to close as many other
applications as you can, before running the plugin, especially
those that tend to work in the background, such as anti-virus
or file-swapping software. Also, if you must leave other
applications open, try to minimize them (i.e. shrink the window
down to the taskbar) so that they stay out of the painting loop.

c. Windows Vista / Winamp with per-user settings
Be aware that if you're running Vista as a non-admin user,
you can't write to (or delete from) files in the Program Files
directory, which is were MilkDrop 2 is installed. So, anything
you try to write or save (like milkdrop's settings file, milk2.ini;
or presets) will probably end up deep in some user-specific,
virtualized "Program Files" directory somewhere on your hard
drive. Yell at Microsoft for this one!

Also, if you installed Winamp with per-user settings (instead of
shared settings) - on any OS, not just Vista - be aware that your
.INI files (milk2.ini, milk2_img.ini, milk2_cfg.ini) are all
stored in a folder like this:

C:\Documents and Settings\\Application Data\Winamp\Plugins

(Note that 'Application Data' is a hidden folder.) However,
presets, textures, and things like that are all shared between
users, in the real [c:\Program Files]\winamp\plugins\milkdrop2 folder.
If you want to keep your presets separate, you can still do that,
though - just put them in a personal folder, and then seek to it
from within MilkDrop. If you're using per-user settings in Winamp,
it will remember which folder you last used.

===Using Line-In===
-----------------------
If you want to use your sound card's Line-In or CD Audio inputs for
sound data (instead of mp3 files), you can do this. Do the following:
1. CONNECT WIRES
Connect your audio source (a stereo, a live feed, whatever) into
the line-in (or microphone) 1/8" jack on your sound card. You
might want to test & verify that your cable is good before doing
this.
2. SELECT SOUND INPUT CHANNEL & ADJUST VOLUME
In Windows, double-click the speaker icon in your systray (where
the clock is). Then, on the menu, go to Options -> Properties
and select the "Recording" option. Then make sure the Line In
(or Microphone) input channel (whichever is appropriate for
your case) is SELECTED (with a check mark) and that the volume
is close to, or at, the maximum. Hit OK.
3. TELL WINAMP TO USE LINE-IN
Open Winamp, and hit CTRL+L (the "Open Location" hotkey). Now
type in "linein://" as the location you want to open. (Leave out
the quotes and make sure you use FORWARD slashes.) Hit PLAY
('x' key for the lazy), and the little built-in oscilloscope (or
spectrum analyzer) in Winamp should start showing your signal.
4. RUN MILKDROP
Run MilkDrop as usual. If the waves are too small or large,
either adjust the volume from Windows' Volume Control, or adjust
the sound level at the source.

If you are doing shows using live audio, and if you have a multiple monitor
setup, you might also want to use the "VJ mode" feature, which lets you
control MilkDrop (even editing shaders on the fly, etc.) via a separate monitor.

Media Library Plugin

2008-09-25T13:10:56Z

Tarik: Protected "Media Library Plugin" [edit=autoconfirmed:move=autoconfirmed]

Plugin struct definition
<source lang="cpp">
typedef struct {
int version;
char *description;
int (*init)(); // return 0 on success, non-zero for failure (quit WON'T be called)
void (*quit)();

// return NONZERO if you accept this message as yours, otherwise 0 to pass it
// to other plugins
INT_PTR (*MessageProc)(int message_type, INT_PTR param1, INT_PTR param2, INT_PTR param3);
//note: INT_PTR becomes 64bit on 64bit compiles... if you don't like windows types or caps, you can #include <stddef.h> and use intptr_t

//all the following data is filled in by the library
HWND hwndWinampParent;
HWND hwndLibraryParent; // send this any of the WM_ML_IPC messages
HINSTANCE hDllInstance;
} winampMediaLibraryPlugin;
</source>

* Plugins work by defining a struct full of functions for Winamp to call. For Media Library plugins, there are three functions.
# Init - called after your plugin is loaded. We need an Init() function (rather than having the plugin doing init is the winampGetMediaLibraryPlugin function) because Winamp needs to give YOU data before you can really do your initialization stuff
# Quit - duh
# MessageProc. This is a function that the Winamp calls when certain events happen, such as someone activating your treeview node in the media library, or someone invoking the send-to menu
* You communicate with Winamp one of two basic ones
# By using SendMessage and sending Winamp or the Media Library window custom messages which are defined in Winamp/wa_ipc.h (for Winamp HWND) and gen_ml/ml.h (for Media Libary HWND). This is the "old" way of doing things but even some newer APIs are still built on this mechanism.
# By retrieving pointers to objects from the Wasabi Service Manager. Winamp has a bunch of APIs that you can grab, and plugins can add additional features that you might want to use. Examples of useful Wasabi objects are the [[Media Library Database API|Local Media API]] (which lets you query against the media library), the [[Application API]] (let's you get version #, build #, path to winamp settings folder, etc), and the [[Playlist Manager API]] (lets you parse playlists, among other things)

ml_xmlex is probably the most useful example of the bunch. ml_ stands for media library plugin. __declspec(dllexport) is a magic keyword for Visual C++ that means that the DLL "exports" this function, meaning that a program that loads the DLL can locate and call this function. Winamp goes through and loads ml_*.dll plugins, looks for "winampGetMediaLibraryPlugin" and if it it exists it calls it. From that function you are supposed to return a struct that defines your plugin. It has the plugin name, some function pointers and some data that winamp will populate with information that'll be helpful to you, like winamp's HWND (window handle).

winampMediaLibraryPlugin is defined in gen_ml/ml.h which is one ugly beast of a file
benski> reupload to [[Image:winampMediaLibraryPlugin.png]]
http://shup.com/Shup/57721/10872016431-ml_xmlex-Microsoft-Visual-C__-%5Bdesign%5D-ml.h.png

So you supply "init", "quit" and "MessageProc" functions as well as a description. Winamp calls Init(), at which point ml_xmlex does two things
# Gets the all-important Wasabi Service Manager object
# tells the media library to add a node to the treeview for itself [[Image:ml_xmlex_in_ml.png]] http://shup.com/Shup/57726/10872016155-Main-Window.png

Plugins can manifest themselves in many ways (or be completely invisible!), just this media library plugin is a good starting point because you don't have to write too much busy-work GUI code.

For Media Library plugins, when the media library needs your plugin (e.g. when the user clicked on you in the media library) it calls your message procedure. xmlview.cpp line 147 is the message procedure. this plugin is only handling one message which is to create a view. there are other messages like "do you want to be on the send-to menu" but this example is keeping it simple.

Main

2008-09-25T13:09:58Z

Tarik: Protected "Main" [edit=autoconfirmed:move=autoconfirmed]

Creating a Classic Skin: [[The Base Skin]] --> [[Main|Paint the Main Window]] --> [[Equalizer|Paint the Equalizer Window]] --> [[Playlist|Paint the Playlist Window]] --> [[Mini-browser|Paint the Minibrowser Window]] --> [[AVS|Paint the AVS Window]] --> [[For_Winamp_2.9/5.x|Paint the Winamp 2.9/5.x Windows]] --> [[Creating Custom Cursors|Create Custom Cursors]] --> [[Editing the Configuration Files|Edit the Configuration Files]] --> [[WSZ Files|Compress to .WSZ format]] --> [[Submitting Your Skin to Winamp.com|Submit to Winamp.com]]

==Skinning The Main Window==
The Winamp main window is probably the most complex window, graphics wise, of all its windows. There are many things going on in that one window at all times. Each part of the main window is divided up into various bitmap images. Here is a list of the images below that actually create the main window.

[[Image:Winamp.gif]]

*Main.bmp
*Titlebar.bmp
*CButtons.bmp
*ShufRep.bmp
*Volume.bmp
*Balance.bmp
*MonoSter.bmp
*Posbar.bmp
*Playpaus.bmp
*Numbers.bmp
*Text.bmp

===Winamp Skins | Main.bmp===

[[Image:main.gif]]

This file provides the background image for Winamp, sections of the other bitmaps are cropped and layered over this background image to create the various states of "on" and "off", buttons, sliders, etc. Many skin artists (skinners) create their own main.bmp image as well as the other components to make their skin as unique as possible. Although the regions in which the buttons can actually be clicked, the artists have a certain amount of pixels to play with for each element. This will enable the skinner to give the illusion of making smaller more precise controls, transparent controls, or even just big silly dumb ones if they wish. The possibilities are simply endless. The skin components are all bitmaps and therefore *cannot support animation or transparencies* The only way to achieve transparency is to use the overlapping area of main.bmp as the background in the various components.

===Winamp Skins | Titlebar.bmp===

[[Image:titlebar.gif]]

Titlebar.bmp provides the title bars for the all the various skinned windows of Winamp. The first of the bars are the graphics for Winamp's main window when that window has focus (the current window on your desktop is said to have the 'focus', and on that window the currently selected control also has the 'focus'). The second bar is the main window's title bar when it does not have the focus. The third and fourth bars provide the graphics for Winamp running in Window Shade mode. The fifth and sixth bars are special. They provide the graphics for the title bar when the Winamp Easter Egg is active. (Easter Eggs are usually useless aspects of a piece of software that the software developers include as a joke or to give credit to something. It's just the programmers trying to have a little fun. do not worry about these last two bars for now.)

To the left of the title bars are a selection of graphics for the windows buttons in their various states.

[[Image:winbut.gif]]

The top row consists of the images for system menu (a.k.a. Winamp's Main Menu), the minimize button, as well as the close button in it's normal state (the way the buttons would look if they weren't clicked). The second row consists of the same set of buttons, however in the pressed state (the way the buttons would look if they were clicked). The third row is the graphics for the WindowShade button where the left image is the image of the button not pressed, and the left is the image of the button pressed. The fourth row contains the images for the button that restores Winamp or its various windows from WindowShade mode to its expanded form, the images being in the same order, the left being not pressed, and the right being the pressed state.

The fifth and final row consists of the images that create the progress bar for Winamp when Winamp is in WindowShade mode. The first part of the row consists of the image for which the seek bar rests in, followed by the slider in various states.

To the right of the title bars are the graphics for the CuttleBar, which is a little strip of buttons to the left of the visualization area of the Winamp main window. At the top the strip is shown in it's un-pressed state. To the right of the first strip is a version of the strip with all the labels removed, this is for the people who turn off the CuttleBar in Winamp's Preferences window. The next row of strips are simply the different states of the CuttleBar with copy of the strip in each of it's five states, one state for each button being pressed.

When modifying the title bar it's important to remember that if you change the appearance of your buttons in the main title bar images, you should also change all the graphics that are relevant to the title bar to match so that they don't look out of place when you press them and remove the focus from the button you had just pressed. Also note that you can not add graphics for components that do not exist, for example adding a spot in WindowShade mode for track title scrolling would not make sense, due to the fact that Winamp wasn't coded with that in mind, leaving that spot you created blank.

===Winamp Skins | ShufRep.bmp===

[[Image:Cbuttons.gif]]

The cbuttons.bmp image provides the images for Winamp's playback control buttons. The top row displays the buttons un-pressed or in their normal state, the second row of graphics are the same buttons except in the pressed state. Remember when skinning this set of components that transparency does not exist, if the button is incorporated into the background, you will have to place the background into the cbuttons.bmp.

===Winamp Skins | ShufRep.bmp===

[[Image:Shufrep.gif]]

Shufrep.bmp provides the graphics for both states of the Shuffle-Play button, Play/Loop button (Repeat), Equalizer button as well as the Playlist button. The top row is the (repeat) loop and shuffle in the off state, the second row, are the loop and shuffle button in the off, clicked state(the button being pressed while the shuffle/loop buttons were in the off state). The third row is loop and shuffle button in the on state, and the fourth row are the buttons being clicked in the on state.

The bottom four images make up the graphics for the Equalizer and Playlist editor buttons in both two states. The first is the Equalizer button in the off state. The second button is the Playlist button in the off state. The third is the Equalizer off state and pressed at the same time. The fourth being the Playlist button in the same state. The next row is the exact same thing, however, instead of the buttons being in the off state, they are on.

The same conditions in regards to transparency that apply for the Cbuttons.bmp image apply for this image as well.

===Winamp Skins | Volume.bmp===

[[Image:Volume.gif]]

The volume.bmp file (partial shown here enlarged at the left) contains a set of of bars and two slider graphics. Depending on how high or low the level of the volume is, Winamp selects one of the bars to demonstrate the level at which the volume is currently at. If the volume is all the way down, it displays the more green bars, if all the way up, it displays the more yellow bars. The first bar is the volume at its lowest level, the last bar is the volume at its maximum level. Fiddle with these graphics yourselves to find out which bar is which level. The bottom contains the sliders control images. The first image being the slider, which is in the clicked, the second being in the un-clicked state.

===Winamp Skins | Balance.bmp===

[[Image:Bal.gif]]

Balance.bmp works virtually identitical to volume.bmp, however, the images in balance need to illustrate the volume coming from either the left, right, or both speakers. This is done by swaying from green to red when moving the slider from one of the sides towards center. Simply color all the bars the way you would do for the volume.bmp and the outcome should be the same.

===Winamp Skins | MonoSter.bmp===

[[Image:Monoster.gif]]

Monoster.bmp provides the indication that the audio source is running in Stereo or Mono mode. The top row shows the "in stereo" indicator as well as the "in mono", indicator. The second row shows the "stereo off" and "mono off" indicators. When Winamp is playing in stereo sound, the "stereo on" with the "mono off" indicators are displayed. When the audio is in mono, the opposite is displayed.

===Winamp Skins | Posbar.bmp===

[[Image:Posbar.gif]]

The posbar.bmp, shown here enlarged, provides the track for the song position slider. At the right side of the image, the song seek slider is shown in both states, pressed and not pressed.

===Winamp Skins | Playpaus.bmp===

[[Image:playpaus.gif]]

The playpaus.bmp file provides indicators that the file being played is playing, paused or stopped. The final item shows whether the file is synchronized or buffered or a break in transmission has been found.

===Winamp Skins | Numbers.bmp===

[[Image:Numbers.gif]]

The numbers.bmp file provides the images for displaying the numbers used in the time display, located directly above the visualizations area.

===Winamp Skins | Text.bmp===

[[Image:Text.gif]]

Text.bmp is performs the same job that numbers.bmp, however, this image isn't as limited in use as numbers.bmp. Text.bmp provides all the text that is used for the track area, Playlist editor, and anywhere else that Winamp uses text within the skinned interface.

Input Plugin

2008-09-25T13:09:48Z

Tarik: Protected "Input Plugin" [edit=autoconfirmed:move=autoconfirmed]

Include files:
:Winamp/in2.h
:Winamp/out.h

Image Writer Service

2008-09-25T13:09:38Z

Tarik: Protected "Image Writer Service" [edit=autoconfirmed:move=autoconfirmed]

api/service/svcs/svc_imgwrite.h

For Winamp 2.9/5.x

2008-09-25T13:09:25Z

Tarik: Protected "For Winamp 2.9/5.x" [edit=autoconfirmed:move=autoconfirmed]

Editing the Configuration Files

2008-09-25T13:09:20Z

Tarik: Protected "Editing the Configuration Files" [edit=autoconfirmed:move=autoconfirmed]

Creating a ClassicPro Skin

2008-09-25T13:09:08Z

Tarik: Protected "Creating a ClassicPro Skin" [edit=autoconfirmed:move=autoconfirmed]

==What is ClassicPro?==
ClassicPro is a plugin for Winamp that will allow you to use a new type of skin in Winamp Media Player. What makes this type of skin different from normal modern skins is that all the coding stuff is already done in one central place so you don't need to be a programmer to create a great Winamp skin anymore!
The advantages are not just for the skinners though, artistic people can now create great skins easily, and this means we'll see more beautiful skins by great artists!

ClassicPro skins use an advanced single-user-interface which is really easy to use. The great thing is cPro appeals both to the advanced Winamp user and the minimalistic user who would for example just want to use the playlist. This means ClassicPro will probably fit you like a glove no matter who you are!
If you are used to a Classic Winamp skin and didn't want to switch to the modern skins of the past then we urge you to give this a test drive since this skin type was designed especially for the old school user who might need a minimalistic approach to their favourite media player.

The 2 main key focus points in the development was as follows:
* Performance - Winamp must load quick and use as little resources running as possible
* Easy Interface - The interface must be easy to understand and give enough play for the experienced users too

[http://cpro.skinconsortium.com/ Download ClassicPro plugin]

==Introduction to ClassicPro skins==
[[Image:http://cpro.skinconsortium.com/images/cpro-promo1_04.jpg]]

ClassicPro skins are basically pre-coded Winamp Modern Skins. The advantage of this is that the skinner dont have to spend months coding the skin anymore and can just edit a few picture files and have a fully working skin. All the coding of the skin is installed in one central place by the cPro plugin and then this plugin is maintained by the developer. So when the plugin installs new features or fixes your skin will automatically have them too.

For more information make a post at their forums:
[http://forums.skinconsortium.com SkinConsortium Forums]

==Tools needed to create a skin==
* Graphics Editor
** Paint, Corel PSP, Adobe PS, GIMP, Paint.NET
* Text Editor
** Notepad, Notepad2, Notepad++
* Archiver
** 7zip, WinZip, WinRar
* ClassicPro plug-in
** [http://cpro.skinconsortium.com/ Download ClassicPro plugin]

==Tutorials==
* [http://cpro.skinconsortium.com/index.php?content=manual Skinners Guide to ClassicPro] by pjn123
** This is the manual released by the developers
* [http://wilian.deviantart.com/art/ClassicPro-Template-pack-95549517 ClassicPro Template pack and Manual] by Wilian & Veroka
** This is a more in depth look at creating cPro skins. Really great for beginners.
** Comes with great base skin for you to start off with

Box source code here

2008-09-25T13:09:02Z

Tarik: Protected "Box source code here" [edit=autoconfirmed:move=autoconfirmed]

'''Breadcrumb''' -- [[Main_Page|Wiki Main]] : [[Skin Developer]] : [[Visual Developer]] : [[Plug-in Developer]] : [[Articles|Articles Page]] : [[Developers FAQ|FAQ]] : [[Main_Page#Glossary_of_Terms|Glossary]]

<source lang=cpp>
#include <windows.h>
#include "resource.h"
#include "avs_ape.h"

// this will be the directory and APE name displayed in
// the AVS Editor
#define MOD_NAME "Tutorials / BOX v1.0"

// this is how WVS will recognize this APE internally
#define UNIQUEIDSTRING "Nullsoft Tut0: BOX"
class C_THISCLASS : public C_RBASE
{protected:
public:
C_THISCLASS();
virtual ~C_THISCLASS();
virtual int render(char visdata[2][2][576], int isBeat,
int *framebuffer, int *fbout, int w, int h);
virtual HWND conf(HINSTANCE hInstance, HWND hwndParent);
virtual char *get_desc();
virtual void load_config(unsigned char *data, int len);
virtual int save_config(unsigned char *data);
int enabled; // toggles plug-in on and off
// (a good idea for any APE)
int color; // color of rectangle};

// global configuration dialog pointer
static C_THISCLASS *g_ConfigThis;
// global DLL instance pointer (not needed in this
// example, but is useful)static HINSTANCE g_hDllInstance;
// this is where we deal with the configuration screen
static BOOL CALLBACK g_DlgProc(HWND hwndDlg, UINT uMsg,
WPARAM wParam,LPARAM lParam)
{
switch (uMsg)
{
case WM_INITDIALOG:
if (g_ConfigThis->enabled)
{
CheckDlgButton(hwndDlg,IDC_CHECK1,BST_CHECKED);
}
return 1;
case WM_DRAWITEM:
DRAWITEMSTRUCT *di;
di=(DRAWITEMSTRUCT *)lParam;
if (di->CtlID == IDC_DEFCOL)
{
int w;
int color;
w=di->rcItem.right-di->rcItem.left;
color=g_ConfigThis->color;
color = ( (color>>16)&0xff) |
(color&0xff00) |
((color<<16)&0xff0000);

// paint nifty color button
HBRUSH hBrush,hOldBrush;
LOGBRUSH lb={BS_SOLID,color,0};
hBrush = CreateBrushIndirect(&lb);
hOldBrush=(HBRUSH)SelectObject(di->hDC,hBrush);
Rectangle(di->hDC,di->rcItem.left,di->rcItem.top,
di->rcItem.right,di->rcItem.bottom);
SelectObject(di->hDC,hOldBrush);
DeleteObject(hBrush);
}
return 0;
case WM_COMMAND:

// see if enable checkbox is checked
if (LOWORD(wParam) == IDC_CHECK1)
{
g_ConfigThis->enabled=
(IsDlgButtonChecked(hwndDlg,IDC_CHECK1)?1:0);
}

// is colorbox is selected?
if (LOWORD(wParam) == IDC_DEFCOL)
{
static COLORREF custcolors[16];
int *a;
CHOOSECOLOR cs;
a=&g_ConfigThis->color;
cs.lStructSize = sizeof(cs);
cs.hwndOwner = hwndDlg;
cs.hInstance = 0;
cs.rgbResult = ((*a>>16)&0xff)|
(*a&0xff00)|
((*a<<16)&0xff0000);
cs.lpCustColors = custcolors;
cs.Flags = CC_RGBINIT|CC_FULLOPEN;

// go to windows color selection screen
if (ChooseColor(&cs))
{
*a = ((cs.rgbResult>>16)&0xff)|
(cs.rgbResult&0xff00)|
((cs.rgbResult<<16)&0xff0000);
}
InvalidateRect(GetDlgItem(hwndDlg,IDC_DEFCOL),
NULL,TRUE);
}
return 0;
}
return 0;
}

// set up default configuration
C_THISCLASS::C_THISCLASS()
{
//set initial color
color=RGB(255,0,0);
enabled=1;}

// virtual destructor
C_THISCLASS::~C_THISCLASS()
{
}

/* RENDER FUNCTION:
render should return 0 if it only used framebuffer,
or 1 if the new output data is in fbout.
this is used when you want to do something that you'd otherwise
need to make a copy of the framebuffer.
w and h are the width and height of the screen, in pixels.
isBeat is 1 if a beat has been detected.
visdata is in the format of [spectrum:0,wave:1][channel][band].
*/

int C_THISCLASS::render(char visdata[2][2][576], int isBeat,
int *framebuffer, int *fbout, int w, int h)
{
int halfw;
int halfh;

// is this effect on?
if (!enabled)
{
return 0;
}

// did we just hit a beat?
if(isBeat)
{
// draw our magic box
halfw=w/2;
halfh=h/2;
framebuffer+=(((halfh/2)*w)+ (halfw/2));
for(int j=0;j<halfh;j++)
{
for(int i=0;i<halfw;i++)
{
framebuffer[i]=color;
}
framebuffer+=w;
}
}
return 0;
}

HWND C_THISCLASS::conf(HINSTANCE hInstance, HWND hwndParent)
// return NULL if no config dialog possible
{
g_ConfigThis = this;
return CreateDialog(hInstance,MAKEINTRESOURCE(IDD_CONFIG),
hwndParent,g_DlgProc);
}
char *C_THISCLASS::get_desc(void)
{
return MOD_NAME;
}

// load_/save_config are called when saving and loading
// presets (.avs files)

#define GET_INT() (data[pos]|(data[pos+1]<<8)|\
(data[pos+2]<<16)|(data[pos+3]<<24))
// read configuration of max length "len" from data.

void C_THISCLASS::load_config(unsigned char *data, int len)
{
int pos=0;
// always ensure there is data to be loaded
if (len-pos >= 4)
{
// load activation toggle
enabled=GET_INT();
pos+=4;
}

if (len-pos >= 4)
{
// load the box color
color=GET_INT();
pos+=4;
}
}

// write configuration to data, return length.
// config data should not exceed 64k.
#define PUT_INT(y) data[pos]=(y)&255; data[pos+1]=(y>>8)&255;\
data[pos+2]=(y>>16)&255; data[pos+3]=(y>>24)&255

int C_THISCLASS::save_config(unsigned char *data)
{
int pos=0;

PUT_INT(enabled);
pos+=4;

PUT_INT(color);
pos+=4;

return pos;
}

/*
export stuff
creates a new effect object if desc is NULL, otherwise
fills in desc with description
*/
C_RBASE *R_RetrFunc(char *desc)
{
if (desc)
{
strcpy(desc,MOD_NAME);
return NULL;
}
return (C_RBASE *) new C_THISCLASS();
}
// allows AVS to retrieve this APE module
extern "C"
{
__declspec (dllexport) int _AVS_APE_RetrFunc(HINSTANCE\
hDllInstance, char **info, int *create)
// return 0 on failure
{
g_hDllInstance=hDllInstance;
*info=UNIQUEIDSTRING;
*create=(int)(void*)R_RetrFunc;
return 1;
}
};
</source>

Album Art API

2008-09-25T13:08:56Z

Tarik: Protected "Album Art API" [edit=autoconfirmed:move=autoconfirmed]

Agave/AlbumArt/api_albumart.h

Wasabi

2008-09-25T13:08:50Z

Tarik: Protected "Wasabi" [edit=autoconfirmed:move=autoconfirmed]

'''W'''inamp '''S'''ervice '''A'''rchitecture '''B'''inary '''I'''nterface
== Rationale ==

The plugin struct definition API is effective, but it would be cumbersome to create a new plugin type for every possible scenario. As a result, a new generic plugin system was created named Wasabi (Winamp Service Architecture Binary Interface). Instead of hard-coded lists of function pointers to be defined, plugins create C++ objects implementing known interfaces identified with some unique ID (GUID). Rather than a specific filename having one specific plugin type (in_*.dll for Input plugins), Wasabi components 'register' the services they provide. This allows one plugin to load provide multiple services, allows for new plugin types to be created without new code, and allows for "specialized" plugin types. For example, playlist.w5s loads the [[Playlist API|Playlist Manager API]] for loading and analyzing playlist files, as well as individual playlist loading objects for each type (M3U, PLS, B4S), and various helper services involving playlists.

Plugins can communicate with each other by requesting each other's services via the Service Manager. They can also query for API's that Winamp itself registers such as the [[System Callbacks API]] (generic notification system) and the [[Application API]] (allows plugins to query for version number, settings path, etc)

Wasabi relies on a common base class called "Dispatchable". Dispatchable implements a single virtual method which consists of a "function ID" integer value, an array of parameters and a parameter count. Child class implementations override this function with logic which "dispatches" each ID to the appropriate function. In some regards, it is similar to the old [[SendMessage API]]. However, a set of inline helper methods defined inside each interface removes the complexity of using Wasabi interfaces, and most of the complexity from implementing Wasabi interfaces. They can be treated like any other C++ object.

== Components of Wasabi ==

* api definitions - formalizes the interfaces for various objects, APIs, interfaces and services
* wasabi helper classes - accesses the service manager to find services to perform required tasks. e.g. FileReaderApi enumerates the available file reader services to find an appropriate one and read from it. Used to hide complexity from the programmer. Some of these exist as shared services, to cut down on duplicate code across plugins.
* general purposes helper classes / functions - called BFC (brennan foundation class) currently.

What is Wasabi intended to solve?

# C++ does not define a binary interface to share objects between modules
# The existing [[SendMessage API|winamp 2]] plugin architecture only defines a limited set of interfaces
# Existing winamp 2 plugins have limited interaction with Winamp.

== Dispatchable ==

The Dispatchable class is the base class for many of the classes within Wasabi. It contains a single virtual method, _dispatch(), which is passed a dispatch ID msg, a pointer to store a return value retval, a pointer to an array of parameters params, and the parameter count nparam.

The class is defined as:

'''class''' Dispatchable
{
'''public''':
// this is virtual so it is visible across modules
'''virtual''' '''int''' _dispatch('''int''' msg, '''void''' *retval, '''void''' **params = NULL, '''int''' nparam = 0)=0;
};

In many ways, it is similiar to the Invoke() portion of COM's IDispatch class. It is also conceptually similiar to a Win32 Window Procedure.

When classes are used by different plugins, the Dispatchable base class is used instead of abstract classes with pure virtual functions. Why? Because it makes it easier to add additional methods, without requiring "version 2" classes such as those that COM uses. (See for example http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmform95/htm/readerobject.asp). And since the handling of an unknown "msg" is uniform, it allows a limited form of forwards compatability as well.

== Interfaces ==

Interfaces that are intended to be shared amongst plugins are defined specially in Wasabi. An interface is derived from Dispatchable and defines a set of dispatch messages which make up the particular interface. Depending on its use, an interface's classname will be given one of the following prefixes

* api - For singleton APIs. Examples of APIs are the Service Manager and the System Callbacks API.
* ifc - For interfaces. These are given to Dispatchable classes which are not involved with the service manager. These are typically used for passing objects to other objects or for accepting objects as return values.
* svc - For collective services. These are services which are one of many classes which implement an interface. Examples include image loading services and playlist loading services.
* obj - For objects. These are classes which are created by the service factory on getInterface() and destroyed on releaseInterface(). Examples of objects are instances of the XML Parser and the JNetLib http retriever.

=== Example ===
The interface for a "Region" (a shape that defines a portion of a window, usually used for painting)

class ifc_region : public Dispatchable
{
public:
int _dispatch(int msg, void *retval, void **params=NULL, int nparam=0);

enum
{
REGION_GETOSHANDLE =50,
REGION_CLONE =100,
REGION_DISPOSECLONE =110,
REGION_PTINREGION =120,
REGION_OFFSET =130,
REGION_GETBOX =140,
REGION_SUBTRACTRGN =150,
REGION_SUBTRACTRECT =160,
REGION_ADDRECT =170,
REGION_ADD =180,
REGION_AND =190,
REGION_SETRECT =200,
REGION_EMPTY =210,
REGION_ISEMPTY =220,
REGION_EQUALS =230,
REGION_ENCLOSED =240,
REGION_INTERSECTRGN =250,
REGION_DOESINTERSECTRGN =251,
REGION_INTERSECTRECT =260,
REGION_ISRECT =270,
REGION_SCALE =280,
REGION_DEBUG =290,
REGION_MAKEWNDREGION =300,
REGION_GETNUMRECTS =310,
REGION_ENUMRECT =320,
};
};

Typically, the Dispatchable classes define non-virtual methods corresponding to each dispatch message. The implementation of these methods are to simply pack the parameters into an array and call _dispatch.

For example:

inline void Region::offset(int x,int y)
{
void *params[2] = {&x, &y};
_dispatch(REGION_OFFSET, NULL, params,2);
}

The purpose of these methods are to allow the interface to be used without having to think about the Dispatchable interface. Once the interface is defined and the helper methods are written you can totally forget about Dispatchable.

Interfaces allow for an object to be shared amongst Winamp and plugins. For example, since api_region is defined, you may call the function api_region *GetUpdateRegion(); and use the returned object safely.
Services

== Services ==

In Wasabi, a service is an object that implements functionality that Winamp or other plugins may require. For example, the image loader service loaded decompresses an image. The memory manager service acts as a common malloc/free, so that memory allocated in one plugin can be freed safely in another.

Services use Interfaces. The GetUpdateRegion example in the Interfaces section described using interfaces to define an object returned from a function. But how does a plugin call a function in Winamp in the first place? That's where services come in.

Services are retrieved through api_service, an interface which is passed to each plugin as it is loaded. api_service acts as a "global store" of services. Plugins can retrieve other services and register their own services.

There are two basic kinds of services, '''''unique''''' services and '''''collective''''' services.

A collective service is an interface which implements a particular service type. Typically, this is a service that has to be implemented differently depending on use. For example, a PNG loading service would be part of the WaSvc::IMAGELOADER service type, and would be a different object from other WaSvc::IMAGELOADER services (such as a JPG loader). File readers are another example: direct file access could be implemented separately from HTTP access, ZIP file access, etc. Clients (Winamp or plugins) can enumerate through all the services of a particular type, to find one that fits its needs.

Unique services are one-off interfaces. They have a service type of WaSvc::UNIQUE. Rather than checking for a particular service type, a client asks for a particular service by GUID. A memory manager service would be a unique service. Typically, unique services are used to provide some sort of system access, or to perform some sort of very specific task.

== Service Factories ==

Services are retrieved via Service Factories. api_service operates with service factories, and plugins must provide service factories for the services they implement. Service Factories create objects of your service whenever requested by a client.

Although the factory is annoying to deal with (just another layer to get to what you want), it allows for the developer to control object creation. Most unique services (and some collective services) are singletons. That is, there only needs to be one of them in existance at any point in time. The same object pointer may be returned every time from the factory.

Other services might be need to be uniquely created for each client. Each file reader, for example, will need a separate object, since state is stored in the file reader object.

Services are released through the factory that created them, allowing the factory to control destruction as well as construction.

== System Callbacks ==
Not technically part of the the api/interface/services infrastructure within Wasabi. System Callbacks (api_syscb), is a service which broadcasts messages to any callback receiver (a class dervied from SysCallback) that has registered itself with the System Callbacks service.

Service registration and deregistration messages are broadcasted by api_service, so api_syscb is guaranteed to be an available service (because it must be created for api_service to operate).

The Base Skin

2008-09-25T13:08:46Z

Tarik: Protected "The Base Skin" [edit=autoconfirmed:move=autoconfirmed]

System Callbacks API

2008-09-25T13:08:38Z

Tarik: Protected "System Callbacks API" [edit=autoconfirmed:move=autoconfirmed]

api/syscb/api_syscb.h

SendMessage API

2008-09-25T13:08:20Z

Tarik: Protected "SendMessage API" [edit=autoconfirmed:move=autoconfirmed]

Include files:
:Winamp/wa_ipc.h
:Winamp/ipc_pe.h

Although Winamp provides input plugins with a number of function pointers to make calls into Winamp, there are simply too many functions in the Winamp SDK to reasonably provide that for every available function. The API was expanded by means of special window messages that could be sent to the main winamp window. Although the API was built this was largely as an historical accident, but this part of API continues to gain new features as it has a number of advantages despite its quirks.
A plugin can call a "function" in Winamp by passing a message with msg id == WM_WA_IPC (defined in Winamp/wa_ipc.h). The lParam value determines what function to call and the wParam contains a parameter relevant to the function (often a pointer to a struct in case multiple parameters are needed). These function calls are referred to as IPC's (inter-plugin communication) Despite the quirkiness and the odd reminiscence to DOS interrupt function calls, it does offer two major advantages:

# Windows automatically runs the SendMessage response on the "main" application thread, allowing plugins to make SendMessage calls on other threads safely.
# *this is important, this is how a lot of stuff gets done by plugins* - By subclassing the main Winamp window, a plugin can alter Winamp's handling of various API calls. This has become such a popular method used by plugin developers that Winamp often sends messages to itself as a way to notify plugins about various events.

Playlist

2008-09-25T13:06:50Z

Tarik: Protected "Playlist" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: XML Intro

2008-09-25T13:06:45Z

Tarik: Protected "Modern Skin: XML Intro" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Skin Scripting

2008-09-25T13:06:37Z

Tarik: Protected "Modern Skin: Skin Scripting" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Relative Positioning

2008-09-25T13:06:23Z

Tarik: Protected "Modern Skin: Relative Positioning" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Layer Composition

2008-09-25T13:06:09Z

Tarik: Protected "Modern Skin: Layer Composition" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Drawers

2008-09-25T13:05:54Z

Tarik: Protected "Modern Skin: Drawers" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Complex Skin

2008-09-25T13:05:45Z

Tarik: Protected "Modern Skin: Complex Skin" [edit=autoconfirmed:move=autoconfirmed]

Modern Skin: Alpha Channels

2008-09-25T13:05:39Z

Tarik: Protected "Modern Skin: Alpha Channels" [edit=autoconfirmed:move=autoconfirmed]

MilkDrop Preset Authoring

2008-09-25T13:05:31Z

Tarik: Protected "MilkDrop Preset Authoring" [edit=autoconfirmed:move=autoconfirmed]

[[Image:Milkdrop.png|right|320px]]
== MILKDROP preset authoring guide ==

Note that there is another, quite comprehensive, Preset Authoring Guide available on the web at http://www.milkdrop.co.uk/, which is continually updated and expanded through the hard work of a few dedicated preset authors. Whereas this guide (the one you are currently viewing) gives the bare technical specifications for writing your own presets, the guide at milkdrop.co.uk 'starts at the beginning' and walks you through all of the mathematics and subtleties of 'rolling your own', explaining things in great detail. The guide at milkdrop.co.uk is very highly recommended to anyone who wishes to learn more about creating their own presets.

== About Presets ==

When you watch MilkDrop, you are watching a series of Presets. Each one has its own look and feel, draws the sound waves in a particular way, and has certain motions to it. After some time, you will see a short blend transition, and then you will be watching a new preset.

A single 'preset' is a collection of parameters that tell MilkDrop how to draw the wave, how to warp the image around, and so on. MilkDrop ships with over 100 built-in presets, each one having a distinct look and feel to it.

Using MilkDrop's built-in "preset-editing menu" (the M key), you can edit presets on the fly, on-screen, from within the program. You can make slight adjustments to existing presets, then save over them; or you can change lots of things, so the preset doesn't look anything like the original, and then save it under a new name. You can even write insane new mathematical equations, of your own imagination, into your preset files and come up with things that MilkDrop has never done before!

Each preset is saved as a file with the ".milk" extension, so you can easily send them to your friends or post them on the web. You can also go to http://www.nullsoft.com/free/milkdrop and then jump to the "preset sharing forum" to see what other people have come up with, or post your own cool, new presets. milkdrop.co.uk/ is another great place to download collections of presets made by others like yourself.

== Preset Authoring - Basic ==

You can edit the properties of the current preset by hitting 'M', which brings up the "preset-editing menu". From this menu you can use the up and down arrow keys to select an item. Press the RIGHT arrow key to move forward through the menu and select the item (note: you can also hit SPACE or RETURN to do this); ***press the LEFT arrow key to go back to the previous menu.***

Pressing 'M' while the menu is already showing will hide the menu; pressing ESCAPE will do the same thing. Press 'M' again to bring the menu back.

Once you've reached an item on the menu whose value can be edited, use the UP and DOWN arrow keys to increase or decrease its value, respectively. Changes will register immediately. Use PAGE UP and PAGE DOWN to increase the value more quickly. Hold down SHIFT and use the UP/DOWN arrow keys to change the value very slowly. Hit RETURN To keep the new value, or ESC to abort the change.

If the item you're editing is a text string, you can use the arrow keys to move around. The Insert key can be used to toggle between insert and overtype modes. You can hold shift and use the arrow keys (home, end, left, right) to make a selection, which will be identified by brackets []. You can then use CTRL-C or CTRL-X to copy or cut text. CTRL-P pastes. When finished editing, hit RETURN To keep the new string, or ESC to abort the change.

You'll want to get into the habit of using SCROLL LOCK whenever you're making changes to a preset that you intend to save;
otherwise, MilkDrop is sure to move you along to a new (random) preset, over time. When the menus are showing, the preset is
automatically temporarily locked, but BE CAREFUL - if you're not also using SCROLL LOCK, then 0.1 seconds after you hide the menu
to take a look at your new masterpiece, MilkDrop might load a random new preset on you, and you'd lose your changes! And you
might then ask me: "how large is large?" And I will tell you: "thirty."

There are also some hotkeys that will allow you to change certain
common parameters to the current preset. These are listed below.

MOTION
i/I - zoom in/out
[ / ] - push motion to the left/right (dx)
{ / } - push motion up/down (dy)
< / > - rotate left/right (rot)
o/O - shrink/grow the amplitude of the warp effect

WAVEFORM
W - cycle through waveforms
j/J - scale waveform down/up
e/E - make the waveform more transparent/more solid

BRIGHTNESS **
g/G - decrease, increase gamma (brightness) **

VIDEO ECHO effect **
q/Q - scale 2nd graphics layer down/up **
F - flip 2nd graphics layer (cycles through 4 fixed orientations) **

** these keys only have an effect if you are running a
MilkDrop 1-era preset. In MilkDrop 2-era presets,
these values are embedded in the shader, so you need
to go into the composite shader and tweak the code.

== Preset Authoring - Advanced ==

This section describes how to use the 'per-frame' and 'per-vertex' equations to develop unique new presets.

=== PER-FRAME EQUATIONS ===

When you hit 'm' to show the preset-editing menu, several items
show up. If you explore the sub-menus, you'll see that
all of the properties that make up the preset you're currently
viewing are there. The values you can specify here (such as
zoom amount, rotation amount, wave color, etc.) are all static
values, meaning that they don't change in time. For example,
take the 'zoom amount' option under the 'motion' submenu.
If this value is 1.0, there is no zoom. If the value is 1.01,
the image zooms in 1% every frame. If the value is 1.10, the
image zooms in 10% every frame. If the value is 0.9, the image
zooms out 10% every frame; and so on.

However, presets get far more interesting if you can take these
parameters (such as the zoom amount) and animate them (make them
change over time). For example, if you could take the 'zoom
amount' parameter and make it oscillate (vary) between 0.9 and
1.1 over time, the image would cyclically zoom in and out, in
time.

You can do this - by writing 'per-frame' and 'per-vertex'
equations. Let's start with 'per-frame' equations. These are
executed once per frame. So, if you were to type the following
equation in:

zoom = zoom + 0.1*sin(time);

...then the zoom amount would oscillate between 0.9 and 1.1
over time. (Recall from your geometry classes that sin()
returns a value between -1 and 1.) The equation says: "take
the static value of 'zoom', then replace it with that value,
plus some variation." This particular equation would oscillate
(cycle) every 6.28 seconds, since the sin() function's
period is 6.28 (PI*2) seconds. If you wanted it to make it
cycle every 2 seconds, you could use:

zoom = zoom + 0.1*sin(time*3.14);

Now, let's say you wanted to make the color of the waveform
(sound wave) that gets plotted on the screen vary through time.
The color is defined by three values, one for each of the main
color components (red, green, and blue), each in the range 0 to 1
(0 is dark, 1 is full intensity). You could use something like this:

wave_r = wave_r + 0.5*sin(time*1.13);
wave_g = wave_g + 0.5*sin(time*1.23);
wave_b = wave_b + 0.5*sin(time*1.33);

It's nice to stagger the frequencies (1.13, 1.23, and 1.33) of
the sine functions for the red, green, and blue color components
of the wave so that they cycle at different rates, to avoid them
always being all the same (which would create a greyscale wave).

Here is a full list of the variables available for writing per-frame
equations:

NAME WRITABLE? RANGE DESCRIPTION
---- --------- ----- -----------
zoom yes >0 controls inward/outward motion. 0.9=zoom out 10% per frame, 1.0=no zoom, 1.1=zoom in 10%
zoomexp yes >0 controls the curvature of the zoom; 1=normal
rot yes controls the amount of rotation. 0=none, 0.1=slightly right, -0.1=slightly clockwise, 0.1=CCW
warp yes >0 controls the magnitude of the warping; 0=none, 1=normal, 2=major warping...
cx yes 0..1 controls where the center of rotation and stretching is, horizontally. 0=left, 0.5=center, 1=right
cy yes 0..1 controls where the center of rotation and stretching is, vertically. 0=top, 0.5=center, 1=bottom
dx yes controls amount of constant horizontal motion; -0.01 = move left 1% per frame, 0=none, 0.01 = move right 1%
dy yes controls amount of constant vertical motion; -0.01 = move up 1% per frame, 0=none, 0.01 = move down 1%
sx yes >0 controls amount of constant horizontal stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
sy yes >0 controls amount of constant vertical stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
wave_mode yes 0,1,2,3,4,5,6,7 controls which of the 8 types of waveform is drawn
wave_x yes 0..1 position of the waveform: 0 = far left edge of screen, 0.5 = center, 1 = far right
wave_y yes 0..1 position of the waveform: 0 = very bottom of screen, 0.5 = center, 1 = top
wave_r yes 0..1 amount of red color in the wave (0..1),
wave_g yes 0..1 amount of green color in the wave (0..1)
wave_b yes 0..1 amount of blue color in the wave (0..1)
wave_a yes 0..1 opacity of the wave (0..1) [0=transparent, 1=opaque]
wave_mystery yes -1..1 what this parameter does is a mystery. (honestly, though, this value does different things for each waveform; for example, it could control angle at which the waveform was drawn.)
wave_usedots yes 0/1 if 1, the waveform is drawn as dots (instead of lines)
wave_thick yes 0/1 if 1, the waveform's lines (or dots) are drawn with double thickness
wave_additive yes 0/1 if 1, the wave is drawn additively, saturating the image at white
wave_brighten yes 0/1 if 1, all 3 r/g/b colors will be scaled up until at least one reaches 1.0
ob_size yes 0..0.5 thickness of the outer border drawn at the edges of the screen every frame
ob_r yes 0..1 amount of red color in the outer border
ob_g yes 0..1 amount of green color in the outer border
ob_b yes 0..1 amount of blue color in the outer border
ob_a yes 0..1 opacity of the outer border (0=transparent, 1=opaque)
ib_size yes 0..0.5 thickness of the inner border drawn at the edges of the screen every frame
ib_r yes 0..1 amount of red color in the inner border
ib_g yes 0..1 amount of green color in the inner border
ib_b yes 0..1 amount of blue color in the inner border
ib_a yes 0..1 opacity of the inner border (0=transparent, 1=opaque)
mv_r yes 0..1 amount of red color in the motion vectors
mv_g yes 0..1 amount of green color in the motion vectors
mv_b yes 0..1 amount of blue color in the motion vectors
mv_a yes 0..1 opacity of the motion vectors (0=transparent, 1=opaque)
mv_x yes 0..64 the number of motion vectors in the X direction
mv_y yes 0..48 the number of motion vectors in the Y direction
mv_l yes 0..5 the length of the motion vectors (0=no trail, 1=normal, 2=double...)
mv_dx yes -1..1 horizontal placement offset of the motion vectors
mv_dy yes -1..1 vertical placement offset of the motion vectors
decay yes 0..1 controls the eventual fade to black; 1=no fade, 0.9=strong fade, 0.98=recommended
gamma yes >0 controls display brightness; 1=normal, 2=double, 3=triple, etc.
echo_zoom yes >0 controls the size of the second graphics layer
echo_alpha yes >0 controls the opacity of the second graphics layer; 0=transparent (off), 0.5=half-mix, 1=opaque
echo_orient yes 0,1,2,3 selects an orientation for the second graphics layer. 0=normal, 1=flip on x, 2=flip on y, 3=flip on both
darken_center yes 0/1 if 1, help keeps the image from getting too bright by continually dimming the center point
wrap yes 0/1 sets whether or not screen elements can drift off of one side and onto the other
invert yes 0/1 inverts the colors in the image
brighten yes 0/1 brightens the darker parts of the image (nonlinear; square root filter)
darken yes 0/1 darkens the brighter parts of the image (nonlinear; squaring filter)
solarize yes 0/1 emphasizes mid-range colors
monitor yes any set this value for debugging your preset code; if you hit the 'N' key,
the value of 'monitor' will be posted in the upper-right corner of milkdrop.
for example, setting "monitor = q3;" would let you keep an eye on q3's value.

time NO >0 retrieves the current time, in seconds, since MilkDrop started running
fps NO >0 retrieves the current framerate, in frames per second.
frame NO retrieves the number of frames of animation elapsed since the program started
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
-note that if Scroll Lock is on, 'progress' will freeze!

bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
mid NO >0 -same, but for mids (middle frequencies)
treb NO >0 -same, but for treble (high) frequencies
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
mid_att NO >0 -same, but for mids (middle frequencies)
treb_att NO >0 -same, but for treble (high) frequencies

meshx NO 8-128 tells you the user's mesh size in the X direction. always an integer value.
meshy NO 6-96 tells you the user's mesh size in the Y direction. always an integer value.
pixelsx NO 16-4096 width of the viz window, in pixels. If Canvas Stretch is on, this is the pre-stretched size. (same as "texsize.x" for shaders)
pixelsy NO 16-4096 height of the viz window, in pixels. If Canvas Stretch is on, this is the pre-stretched size. (same as "texsize.y" for shaders)
aspectx NO >0 multiply an x-coordinate by this to make the preset look the same at any aspect (window height:width) ratio.
-value: if widescreen, 1; if window is tall, h/w.
aspecty NO >0 multiply a y-coordinate by this to make the preset look the same at any aspect (window height:width) ratio.
-value: if widescreen, w/h; if window is tall, 1.

blur1_min yes 0..1 Normally these are set to 0 (min) and 1 (max).
blur2_min yes 0..1 You can clamp the values in the blur texture to a tighter
blur3_min yes 0..1 range, though.
blur1_max yes 0..1 This will increase the precision in the blur textures,
blur2_max yes 0..1 but you run the risk of clamping values to your min/max.
blur3_max yes 0..1 If you use the GetBlur1() .. GetBlur3() functions to sample
blur1_edge_darken yes 0..1 the blur texture, they will automatically "unpack" the
values for you in the end!

q1 yes any } Used to carry values along a chain
q2 yes any } from the preset init code,
q3 yes any } to the preset per-frame code, then on
q4 yes any } to the preset per-vertex code;
q5 yes any } or to the custom shape per-frame code,
q6 yes any } or to the custom wave per-frame code,
q7 yes any } then to the custom wave per-vertex code;
... } or to the [pixel] shader code.
q31 yes any } Click here to see a diagram for the Q vars.
q32 yes any }

Some of the variables are read-only, meaning that you shouldn't change
their values them through the equations. You can; it won't stop you;
but the results are unpredictable.

You can also make up to 30 of your own variables. For example:

my_volume = (bass + mid + treb)/3;
zoom = zoom + 0.1*(my_volume - 1);

This would make the zoom amount increase when the music is loud,
and decrease when the music is quiet.

HOWEVER, custom variables do not carry over from per-frame equations
to per-vertex equations; if you set a custom variable's value in the
per-frame equations, and try to read it in the per-vertex equations,
you will not get the correct value. Instead, you have to "bridge the
gap" using 32 special variables: q1 through q32. This is usually only
used when you want to precompute some custom values in the per-frame
equations for later use in the per-vertex equations (or for use in
the pixel shaders). For a good example of this, see the 'dynamic swirls'
preset. See below for more information on q1-q32.

=== PER-VERTEX EQUATIONS ===

So far we've discussed only how to change parameters based on
time. What if you wanted to also vary a parameter, such as the
zoom amount, in different ways, for different locations on the
screen? For example, normally, the result of the 'zoom' parameter
is to just do a flat zoom. This doesn't look very realistic,
because you don't see any perspective in the zoom. It would be
better if we could give a unique zoom amount to each pixel on
the screen; we could make the pixels far away from the center
zoom more, and this would give it more perspective. In order
to do this, we use "per-vertex" equations, instead of per-frame
equations.

The code for this per-vertex equation is simple:

zoom = zoom + rad*0.1;

Where 'rad' is the radius of the pixel if it were cast into
polar coordinates; from another perspective, 'rad' is the distance
of the pixel from the center of the screen. 'rad is zero at the
center, and 1 at the corners. So if we run the above code,
the image will be zoomed into 10% more at the edges of the screen
than at the center.

The per-vertex equations are really just like the per-frame equations,
except for a variables. The following variables are available
exclusively to per-vertex equations (and not to per-frame equations):

NAME WRITEABLE? RANGE DESCRIPTION
---- ---------- ----- -----------
x NO 0..1 retrieves the x-position of the current pixel. At the very left edge of the screen this would be 0; in the middle, 0.5; and at the right, 1.
y NO 0..1 retrieves the y-position of the current pixel. At the very top edge of the screen this would be 0; in the middle, 0.5; and at the bottom, 1.
rad NO 0..1 retrives the distance of the pixel from the center of the screen. At the center of the screen this will be zero, and at the corners, 1.
(The middle of the edges will be 0.707 (half of the square root of 2).
ang NO 0..6.28 retrieves the angle of the current pixel, with respect to the center of the screen.
If the point is to the right of the center, this is zero; above it, it is PI/2 (1.57); to the left, it is PI (3.14); and below, it is 4.71 (PI*3/2).
If it is just a dab below being directly to the right of the center of the screen, the value will approach 6.28 (PI*2).
(note: this is simply the arctangent of y over x, precomputed for you.)

zoom yes >0 controls inward/outward motion. 0.9=zoom out 10% per frame, 1.0=no zoom, 1.1=zoom in 10%
zoomexp yes >0 controls the curvature of the zoom; 1=normal
rot yes controls the amount of rotation. 0=none, 0.1=slightly right, -0.1=slightly clockwise, 0.1=CCW
warp yes >0 controls the magnitude of the warping; 0=none, 1=normal, 2=major warping...
cx yes 0..1 controls where the center of rotation and stretching is, horizontally. 0=left, 0.5=center, 1=right
cy yes 0..1 controls where the center of rotation and stretching is, vertically. 0=top, 0.5=center, 1=bottom
dx yes controls amount of constant horizontal motion; -0.01 = move left 1% per frame, 0=none, 0.01 = move right 1%
dy yes controls amount of constant vertical motion; -0.01 = move up 1% per frame, 0=none, 0.01 = move down 1%
sx yes >0 controls amount of constant horizontal stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
sy yes >0 controls amount of constant vertical stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%

time NO >0 retrieves the current time, in seconds, since MilkDrop started running
fps NO >0 retrieves the current framerate, in frames per second.
frame NO retrieves the number of frames of animation elapsed since the program started
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
-note that if Scroll Lock is on, 'progress' will freeze!

bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
mid NO >0 -same, but for mids (middle frequencies)
treb NO >0 -same, but for treble (high) frequencies
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
mid_att NO >0 -same, but for mids (middle frequencies)
treb_att NO >0 -same, but for treble (high) frequencies

meshx NO 8-192 tells you the user's mesh size in the X direction. always an integer value.
meshy NO 6-144 tells you the user's mesh size in the Y direction. always an integer value.
pixelsx NO 16-4096 width of the viz window, in pixels. If Canvas Stretch is on, this is the pre-stretched size. (same as "texsize.x" for shaders)
pixelsy NO 16-4096 height of the viz window, in pixels. If Canvas Stretch is on, this is the pre-stretched size. (same as "texsize.y" for shaders)
aspectx NO >0 multiply an x-coordinate by this to make the preset look the same at any aspect (window height:width) ratio.
-value: if widescreen, 1; if window is tall, h/w.
aspecty NO >0 multiply a y-coordinate by this to make the preset look the same at any aspect (window height:width) ratio.
-value: if widescreen, w/h; if window is tall, 1.

q1 yes any } Used to carry values along a chain
q2 yes any } from the preset init code,
q3 yes any } to the preset per-frame code, then on
q4 yes any } to the preset per-vertex code;
q5 yes any } or to the custom shape per-frame code,
q6 yes any } or to the custom wave per-frame code,
q7 yes any } then to the custom wave per-vertex code;
... } or to the [pixel] shader code.
q31 yes any } Click here to see a diagram for the Q vars.
q32 yes any }

The main reason for distinction between per-frame and per-vertex equations
is simple: SPEED. If you have a per-vertex equation that doesn't make use
of the x, y, rad, or ang variables, then there's no reason for it to be
executed per-vertex; it could be executed once per frame, and the result
would be the same. So, here's a maxim to write on the wall:

"If a per-vertex equation doesn't use at least one of the variables
{ x, y, rad, ang }, then it should be actually be a per-frame
equation."

You might be wondering how on earth all these formulas could be computed
for every pixel on the screen, every frame, and still yield a high frame
rate. Well, that's the magic of the hamster. And the fact that it really
does the processing only at certain points on the screen, then interpolates
the results across the space between the points. In the config panel,
the "mesh size" option defines how many points (in X and Y) there are at
which the per-vertex equations are actually computed. When you crank this
option up, you start eating up CPU cycles rather quickly.

=== VARIABLE POOLS; DECLARING YOUR OWN VARIABLES; PERSISTENCE OF VALUES ===
-----------------------
Declaring and using your own variables is easy - in some bit of code
(init equations, per-frame equations, etc.) you just write something like
the following:

billy = 5.3;

This creates a variable called 'billy' and sets its value to 5.3. You can
then freely read and/or modify the value of 'billy' within that section
of code.

However, sometimes it is desireable to create (really, initialize) a variable
in an "init" equations, then use and/or update it in the "per-frame" equations.
You can always do this, because paired init and per-frame equations
share the same variable pool. In addition, the values of user-defined
variables will persist from frame to frame.

There are three variable "pools" in MilkDrop:

1. preset init code + preset per-frame code
2. custom wave init + custom wave per-frame code
3. custom shape init + custom shape per-frame code

So, you can probably guess that if you declare a variable in the preset
init code, you can then read it in the preset per-frame code. You can
also write to it (update it), and its value will persist to the next
frame. All three pools work this way.

As explained, though, you can't read the value of 'billy' in when in another
variable pool. (This is intentional, and keeps MilkDrop running nice and
fast.) If you want to pass values around between variable pools, you need
to use a set of special variables: q1, q2, q3, etc. on up to q32. See
the next section for details on how they work and how to properly use them.
Just remember: the Q variables (and later, the T variables) are the only ones
that you can use to "jump" between (carry values between) variable pools.

You might notice that there are two other types of equations that weren't
listed above. They are:

* preset per-vertex code
* custom wave per-point code

For these two code sections, persistent values don't really make sense,
because there is no way to properly initialize them. Any user-defined
variables in these code sections should just be treated as scratch
variables, not persisting from frame to frame, from vertex to vertex,
or from point to point (even though technically, they will... but it
probably won't be what you want). The only thing that really makes sense
here is when you want to carry values along from point to point as
you run the custom wave per-point code; to do this, use q1-q32. (See
the next section for a more detailed explanation.)

=== PRESET INIT CODE; CARRYING VALUES BETWEEN VARIABLE POOLS, USING q1-q32 ===
As we've just seen, you can't normally pass values around between variable
pools. However, there is one mechanism for bridging this gap: the 'Q'
variables. They are named q1, q2, q3, and so on, through q32. Their
main function is to bridge the gap between various variable pools.

In MilkDrop 1.03 and later, you can write code that is executed only once,
when a preset is loaded (switched to). This 'preset initialization' code
does two useful things:

1. It allows you to set the initial value of your own (user-defined)
variables (such as 'my_variable'), as just explained.

2. It allows you to write the default ("sticky") values for q1, q2, q3...
through q32. Whatever these values end up at after the init code,
those are the values that q1-q32 will be reset to at the start of
each frame (...the input to the per-frame equations). If the
per-frame equations change the values of q1-q32, those new values will
propagate on to other variable pools (see the diagram below), but on
the next frame, the values will be reset to the original "sticky"
defaults.

See the flow chart below for a brief, and complete, glance at how the values
of the Q variables flow throughout MilkDrop.

Let's walk through the flow of the chart.

If you write to the values of q1..q32 from the "preset init code", the values
you write will become the new 'base values' to which q1..q32 are initialized
at the start of each frame, for the per-frame code. So when you access (read)
q1-q32 in the per-frame code, you'll get the values that were *initially* set -
over and over, every frame. You can then modify them (or not) in the per-frame
code, and the (possibly modified values) will then be readable by the per-vertex
code - as well as by all pixel shader code, and others. However, any modified
values will not persist to the next frame; they will be reset again, at the
start of the next frame, to the values they had at the end of the preset init
code.

In the per-vertex code, the q1-q32 values start (for the first vertex
in any frame) as the values they had at the end of the per-frame code. If you
modify q1-q32 in the per-vertex code, those modified values will carry over
from vertex to vertex. (This isn't a very desireable effect; you should avoid
writing to the Q variables from the per-vertex equations.) Next frame, they
will be reset to whatever value they had at the end of the [next frame's
execution of the] per-frame code. (It's all in the diagram... look at that,
and you'll just get it.)

There is one trick here. You might notice that the custom wave/shape
init boxes are missing from the diagram. That's because the q
variables coming out of them don't go anywhere. The Q values that come
into the per-frame wave/shape equations come from the preset per-frame
equations, as you can see. But, just to humor you: in the wave/shape init code,
the Q values coming in are the results from the preset init code. Any Q values
you write to there (in the wave/shape init code) will be meaningless; although
you can write to (initialize) your own custom variables, and read those in
later, in the wave/shape per-frame equations! So, really, you can still route
data that way, if you really want to.

Side note: when you edit the preset init code and apply it (by hitting
CTRL+ENTER), the init code will re-execute immediately. However, when you
edit the regular per-frame/per-vertex code and hit CTRL+ENTER, the preset init
code will NOT be re-executed; the results of the last execution will persist.
If you change per-frame/per-vertex code and want to re-execute the initialization
code (i.e. to randomize it or reset the preset), you'll have to save the preset
and then re-load it.

(Historical note: nothing here has changed since MilkDrop 1; these diagrams were
just re-designed to be much simpler to read. Actually, there was a bug in
the old diagrams that is now fixed: on frame 0, they showed the Q values
going straight from the (frame 0!?) per-frame code, into the custom
wave/shape init code. On frame 0, those Q values actually come straight from
the preset init code. HOWEVER, they are virtually useless, as discussed above.)

=== CUSTOM SHAPES AND WAVES ===
----------------------
As of MilkDrop 1.04, two new features are available: custom shapes, and custom
waves. A preset can have up to 4 of each.

With custom shapes, you can draw an n-sided shape (with 3-100 sides) anywhere
on the screen, at any angle and size, in any color, and at any opacity. You
even have the option to map the previous frame's image onto the shape, which
makes for some incredible possibilities (such as realtime hardware fractals -
see the 'Geiss - Feedback' preset). You can also write per-frame code to
control all of these things about the shape(s). This way, they can react to
the audio or change over time - whatever you can imagine. You are limited to
four custom shapes per preset, however, each one of those can be instanced,
which lets you draw a huge number (up to 1024) of them each frame, if you
want to, and each one can be totally different (as long as the value of
the 'instance' variable ends up influencing the other properties).

With custom waves, you can draw the waveform (or the frequency spectrum)
wherever, whenever, and however you want; a great addition since MilkDrop
1.03, where only the built-in waveforms were possible. With custom waves
you can also write per-frame code to control the waves, and per-point code
to place every point (or line segment) on the wave exactly where you want,
and in exactly the color you want, and so on.

Remember those q1-q32 variables that were committed at the end of the preset
initialization code, then reset (to those values) at the beginning of each
frame, and then (potentially) modified in the preset per-frame code? Those
(potentially modified) values of q1-q32 - as they were at the end of the
preset's per-frame code, each frame - are piped into the custom wave & custom
shape per-frame code. So if you read 'q3' in the custom wave per-frame
code, what you're really reading is the value of 'q3' as it was left at the
end of this frame's per-frame code. Again, see the q_vars.gif image
for a diagram of the flow of the values of the q1-q32 varibles.

For custom waves and shapes, you can modify q1-q32, if you like, in the per-
frame equations. As usual, the values of the Q variables will not persist
from frame to frame, though - they are reset on each new frame, to match
the values they had at the end of the *preset's* per-frame code, this frame.

For custom waves, you also have one more link in the chain: per-point
(aka per-vertex) code. This code is executed once for each data point in the
waveform. The initial values of q1-q32 coming in (for the first point)
are the values that stood at the end of the custom wave per-frame code,
this frame. If you then modify q1-q32 in the per-point code (or even if you
don't), the values will pass on to the next point. You could, for example,
smooth out a waveform using this.

THE 'T' VARIABLES
----------------------
There are 8 additional variables available for custom waves and shapes:
t1-t8. These are very similar to the Q variables, but they exist only
for custom waves & shapes. To see how the data flows from variable pool
to variable pool for the T vars, take a look at the diagram below. Like
the Q variables, they exist to help you bridge some gaps between variable
pools. However, the T variables are a bit simpler to understand than the
Q's. The diagram below should explain it all.

CUSTOM SHAPE PER-FRAME VARIABLES
----------------------
NAME WRITABLE? RANGE DESCRIPTION
---- --------- ----- -----------
num_inst no 1-1024 The total # of instances (the number of times to repeat the per-frame equations for, & draw, this shape).
instance no 0..num_inst-1 The current instance number that the equations are being executed for.
sides yes 3-100 the default number of sides that make up the polygonal shape
thick yes 0/1 if ON, the border will be overdrawn 4X to make it thicker, bolder, and more visible
additive yes 0/1 if ON, the shape will add color to sature the image toward white; otherwise, it will replace what's there.
x yes 0..1 default x position of the shape (0..1; 0=left side, 1=right side)
y yes 0..1 default y position of the shape (0..1; 0=bottom, 1=top of screen)
rad yes 0+ default radius of the shape (0+)
ang yes 0..6.28 default rotation angle of the shape (0...2*pi)
textured yes 0/1 if ON, the shape will be textured with the image from the previous frame
tex_zoom yes >0 the portion of the previous frame's image to use with the shape
tex_ang yes 0..6.28 the angle at which to rotate the previous frame's image before applying it to the shape
r yes 0..1 default amount of red color toward the center of the shape (0..1)
g yes 0..1 default amount of green color toward the center of the shape (0..1)
b yes 0..1 default amount of blue color toward the center of the shape (0..1)
a yes 0..1 default opacity of the center of the shape; 0=transparent, 1=opaque
r2 yes 0..1 default amount of red color toward the outer edge of the shape (0..1)
g2 yes 0..1 default amount of green color toward the outer edge of the shape (0..1)
b2 yes 0..1 default amount of blue color toward the outer edge of the shape (0..1)
a2 yes 0..1 default opacity of the outer edge of the shape; 0=transparent, 1=opaque
border_r yes 0..1 default amount of red color in the shape's border (0..1)
border_g yes 0..1 default amount of green color in the shape's border (0..1)
border_b yes 0..1 default amount of blue color in the shape's border (0..1)
border_a yes 0..1 default opacity of the shape's border; 0=transparent, 1=opaque

time NO >0 retrieves the current time, in seconds, since MilkDrop started running
fps NO >0 retrieves the current framerate, in frames per second.
frame NO retrieves the number of frames of animation elapsed since the program started
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
-note that if Scroll Lock is on, 'progress' will freeze!

bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
mid NO >0 -same, but for mids (middle frequencies)
treb NO >0 -same, but for treble (high) frequencies
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
mid_att NO >0 -same, but for mids (middle frequencies)
treb_att NO >0 -same, but for treble (high) frequencies

q1 yes any } Used to carry values along a chain
q2 yes any } from the preset init code,
q3 yes any } to the preset per-frame code, then on
q4 yes any } to the preset per-vertex code;
q5 yes any } or to the custom shape per-frame code,
q6 yes any } or to the custom wave per-frame code,
q7 yes any } then to the custom wave per-vertex code;
... } or to the [pixel] shader code.
q31 yes any } Click here to see a diagram for the Q vars.
q32 yes any }

t1 yes any } Used to carry information
t2 yes any } from the custom shape init code
t3 yes any } to the custom shape per-frame code.
t4 yes any } Click here to see a diagram for the T vars.
t5 yes any }
t6 yes any }
t7 yes any }
t8 yes any }

CUSTOM WAVE PER-FRAME VARIABLES
---------------------
NAME WRITABLE? RANGE DESCRIPTION
---- --------- ----- -----------
r yes 0..1 base amount of red color in the wave (0..1)
g yes 0..1 base amount of green color in the wave (0..1)
b yes 0..1 base amount of blue color in the wave (0..1)
a yes 0..1 base opacity of the waveform; 0=transparent, 1=opaque
samples yes 0-512 read: retrieves the # of samples specified for this custom wave (from the menu).
write: lets you dynamically change that #, frame to frame.

time NO >0 retrieves the current time, in seconds, since MilkDrop started running
fps NO >0 retrieves the current framerate, in frames per second.
frame NO retrieves the number of frames of animation elapsed since the program started
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
-note that if Scroll Lock is on, 'progress' will freeze!

bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
mid NO >0 -same, but for mids (middle frequencies)
treb NO >0 -same, but for treble (high) frequencies
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
mid_att NO >0 -same, but for mids (middle frequencies)
treb_att NO >0 -same, but for treble (high) frequencies

q1 yes any } Used to carry values along a chain
q2 yes any } from the preset init code,
q3 yes any } to the preset per-frame code, then on
q4 yes any } to the preset per-vertex code;
q5 yes any } or to the custom shape per-frame code,
q6 yes any } or to the custom wave per-frame code,
q7 yes any } then to the custom wave per-vertex code;
... } or to the [pixel] shader code.
q31 yes any } Click here to see a diagram for the Q vars.
q32 yes any }

t1 yes any } Used to carry information
t2 yes any } from the custom wave init code,
t3 yes any } to the custom wave per-frame code,
t4 yes any } then on to the custom wave per-point code
t5 yes any } (and from point to point, too, if you write
t6 yes any } to the values from the per-point equations).
t7 yes any } Click here to see a diagram for the T vars.
t8 yes any }

CUSTOM WAVE PER-POINT (aka PER-VERTEX) VARIABLES
---------------------
NAME WRITABLE? RANGE DESCRIPTION
---- --------- ----- -----------
x yes 0..1 the x position of this point that makes up the wave (0=left, 1=right)
y yes 0..1 the y position of this point that makes up the wave (0=bottom, 1=top)
sample no 0..1 how far along we are, through the samples that make up the waveform: 0=first sample, 0.5 = half-way through; 1=last sample.
value1 no any the value of the Left audio channel sample at this point in the waveform (or freq. spectrum).
value2 no any the value of the Right audio channel sample at this point in the waveform (or freq. spectrum).
r yes 0..1 amount of red color in this point of the wave (0..1)
g yes 0..1 amount of green color in this point of the wave (0..1)
b yes 0..1 amount of blue color in this point of the wave (0..1)
a yes 0..1 opacity of this point of the waveform; 0=transparent, 1=opaque

time NO >0 retrieves the current time, in seconds, since MilkDrop started running
fps NO >0 retrieves the current framerate, in frames per second.
frame NO retrieves the number of frames of animation elapsed since the program started
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
-note that if Scroll Lock is on, 'progress' will freeze!

bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
mid NO >0 -same, but for mids (middle frequencies)
treb NO >0 -same, but for treble (high) frequencies
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
mid_att NO >0 -same, but for mids (middle frequencies)
treb_att NO >0 -same, but for treble (high) frequencies

q1 yes any } Used to carry values along a chain
q2 yes any } from the preset init code,
q3 yes any } to the preset per-frame code, then on
q4 yes any } to the preset per-vertex code;
q5 yes any } or to the custom shape per-frame code,
q6 yes any } or to the custom wave per-frame code,
q7 yes any } then to the custom wave per-vertex code;
... } or to the [pixel] shader code.
q31 yes any } Click here to see a diagram for the Q vars.
q32 yes any }

t1 yes any } Used to carry information
t2 yes any } from the custom wave init code,
t3 yes any } to the custom wave per-frame code,
t4 yes any } then on to the custom wave per-point code
t5 yes any } (and from point to point, too, if you write
t6 yes any } to the values from the per-point equations).
t7 yes any } Click here to see a diagram for the T vars.
t8 yes any }

=== PIXEL SHADERS ===

The world of realtime computer graphics made a huge stride around 2002-2003, with the advent of pixel shaders. Lots of people want to learn how to use pixel shaders; writing presets for MilkDrop is a great way to learn them, because you get to see the effects of your code instantly,on the screen.

MilkDrop 1 ran on what is called the "fixed function" graphics pipeline. That meant that certain common graphics operations - and very few of them - could be executed for each pixel. You could do a few things - maybe multiply by a texture or a color, then maybe one more simple operation - but that was about it.

Newer presets (MilkDrop 2 and later) can take advantage of programmable pixel shaders. GPUs (graphics processing units) are now capable of executing dozens, even thousands (on more expensive hardware) of instructions per pixel. To tell the GPU what to do at each pixel, you write some code called a "pixel shader". It looks a lot like C, except you'll see the types float3 (...often representing a color, or maybe a 3D coordinate), as well as float2 and float4, as often as you'll see the simple "float" type. There is also a lot of emphasis on sampling from textures.
Textures can either be procedural (like the image from the previous
frame, or a nicely gaussian-blurred version of it, or a procedurally-
generated noise texture), or they can be loaded from disk. To sample
from a texture on disk (...but cached in video memory, of course),
in the shader, you simply specify the name of the image file you want to load,
and how you want to sample it (what kind of filtering & wrapping) as well as
where (the UV coordinates, like XY coordinates, always in the [0..1] range).
It reads the sample (as a float4 - some image formats have four channels
instead of just r/g/b). You can then do whatever you like (mathematically)
with that sample, take other samples, combine them, and so on. The final
output of the shader is always a color value, and it is this color value
that is written to the render target (an internal texture, or the screen).

SHADER MODELS - 2.0, 3.0, etc.
------------------------------
Since pixel shaders were born, there have been a few revisions. Each new
model has more capabilities than the last.

MilkDrop 1 only supports fixed-function graphics - i.e. no pixel shaders.
MilkDrop 2 supports shader model 2 at the lowest level. (If your GPU
doesn't support this, MilkDrop 2 should still run - it just won't show
you any presets that use pixel shaders.) Shader model 2 has a limit of
64 instructions (per shader), though.

Presets can be authored to use Shader Model 3, however. This shader
model is not as widely supported (...so be careful writing presets for
it - half of the GPUs out there don't support it yet, so the preset
won't show up in the preset list on those computers). However, it is
much more powerful, with a virtually unlimited number of instructions.
(You're just limited by the speed of your GPU and the number of pixels
you need to draw each frame!) On a GeForce 8000-series, believe it
or not, you can easily achieve smooth framerates running shaders with
THOUSANDS of instructions!

Shader Model 4.0 also exists, but only in DirectX 10; and DirectX 10
is only available with Windows Vista. Because not many people have
Vista yet, we've decided to wait (a damn long time) until going down
that path. Shader Model 3 has virtually everything we need in it
anyway.

PRESET FILE VERSIONS & COMPATIBILITY
------------------------------------
Note that if you load a MilkDrop 1 preset, you can save it back to disk
(even after changing code, variables, etc.) and it will still be readable
by MilkDrop 1. Only if you select the menu option to "Upgrade [its]
Pixel Shader Version" will you be making it no longer backwards-compatible.
Once you've done this, though, you'll notice that the menus look slightly
different - some new shader-based options will appear, and some old stuff
(video echo, gamma, etc. - all things that are now folded into the
composite shader) are all gone. You'll also notice that two nice little
default shaders (warp and composite) have been written for you, and that
the relevant values and options from the old preset (gamma, decay, video
echo, texture wrap, etc.) have all been set correctly in the new shaders,
so that the preset does exactly what it did before. The only difference
is that now, the preset takes advantage of the full programmability of
pixel shaders (and you have a lot of freedom to tweak it), instead of
being restricted by the highly restrictive DX8 fixed-function graphics
pipeline.

Some of the mash-up functions (discussed later) will mix old and new
presets together. In this case, the newly-created preset file will only
look correct on MilkDrop 1.xx if it uses neither a warp nor composite shader.
It will still run in MilkDrop 1, but without shaders, so whatever random
values gamma, video echo, etc. were left at, will all kick back in.

One last note: keep in mind that MilkDrop 2 is smart enough to not show
you any presets that your GPU can't support. MilkDrop 1, though, isn't
so smart - it will let you look at MilkDrop 2 presets. It will
ignore all the shader stuff, and probably not display correctly, though.

==== A PIXEL SHADER - CONCEPTUAL OVERVIEW ====

Games are what have driven the Hardware Graphics revolution, and games work by projecting many thousands of 3D triangles onto your screen and rasterizing (pixelizing) & shading them. In MilkDrop, also, your graphics processing unit (GPU) is told to draw many triangle onto your screen. Each is described by three vertices (points). The interior of the triangle is a bunch of pixels. The GPU runs your "shader" code on each pixel to determine how to shade the pixel - i.e., light it, or determine its color. (The terminology is more geared toward the idea that these triangles were originally in 3D and require realistic lighting and shading.)

In MilkDrop, the shaders are run on a dumb, regular grid of triangles that covers the entire visualizer window. The results of the preset's per-vertex equations are interpolated across the face of each of these triangles, and your pixel shader will see the interpolated results. They come in in the form of "UV" coordinates - they tell you where to sample (read) the source image, in order to create the desired warping effect each frame - the long-term effect of which is to create perceived motion.

You can then sample that image (or others), do some math on the result, sample some other textures, do some more math, etc. By the end of the shader, whatever value is in "ret" (a float3 - three floating-point values) is the color that will be written for that pixel.

Each preset in MilkDrop 2 has two pixel shaders: the warp shader,
which warps the image from frame to frame, and the composite shader,
which draws the frame to the screen (with or without special effects).

To edit or experiment with these shaders, while MilkDrop is running,
hit 'M' to view the preset editing menu. The scroll down to either
[edit warp shader]
or
[edit composite shader]
and hit ENTER. If you don't see either of these options, it means
the current preset is an old MilkDrop 1 preset; in this case, you can
either try a different preset, or you can upgrade the current preset
by selecting

update preset's pixel shader version

toward the bottom of the menu. Keep in mind that if you upgrade
a preset's pixel shader version and then save it to disk, it might
not be usable anymore on other computers with older graphics chips.

Now go edit one of the two shaders. Once you're in there, editing,
hit F9 - this will toggle the onscreen quick reference for writing
shaders. It's very handy. Press F9 again to hide it.

==== WARP SHADER ====

Here is an example of a simple WARP shader. It is run over every pixel of
the internal canvas, with the output being back to the canvas itself (it's
a double-buffered texture). Any special effects that happen here get "baked"
into the image, and will persist into the next frame.

shader_body
{
// sample a pixel from the previous frame.
// uv coord is slightly warped (driven by the per-vertex equations),
// and is what creates the main "movement" in our preset.
ret = tex2D( sampler_main, uv ).xyz;

// darken over time
ret *= 0.97;
}

There are only two instructions here... sample the old frame, and
darken the old color value (color values are always in the 0..1 range)
to prevent the screen from turning white over time.

This code is run on every pixel on the screen. If the UV's coming in
were just [0..1] on X and Y, corresponding exactly to the location of
the pixel on the screen, there would be no movement (or warp).
What creates the warp is that the UV coordinates are slightly "off".
Each frame, MilkDrop executes the per-vertex equations for the current
preset at all the vertices on a grid covering the screen. The resulting
UV coordinates are then interpolated (by the GPU) between the vertices,
and this shader code is executed at each pixel, with the UV coordinates
smoothly interpolated for you to do your sampling. Note that the
original, un-distorted UV coordinates are always available in uv_orig.
If the preset had no motion in it, or if we used uv_orig instead of uv,
we would just see pixels getting darker over time, with no apparent motion.

Note that MilkDrop's internal canvas (texture) can only store colors
in the [0..1] range, so if your shader outputs values beyond that range,
the values will be clipped to 0 or 1. Within the body of the shader,
you can go nuts, using any number ranges you want; this restriction only
applies to the final output.

Note that there are several ways to darken pixels over time, and the
color precision (8 bits per color channel, or 256 shades, or [0..1]
in increments of 0.004) means you have to be careful about darkening
the color over time. If you're going to darken using this:

ret *= 0.97;

then you shouldn't use a multiplier above 0.98, because, due to precision,
dark-ish pixels will never become fully dark. Another way to do it
is this:

ret -= 0.004;

The above darkening method will make the pixels go dark, although,
sometimes too quickly. One way around this is to use error diffusion
dithering (discussed later in this guide).

Probably the best thing is to combine the two:

ret = (ret - 0.002)*0.99;

This gives you a partially constant, partially linear darkening effect,
and it tends to look the best. Tweak the values as needed.

==== COMPOSITE SHADER ====

Here is an example of a simple COMPOSITE shader. It is run over every
pixel in the visualizer window, the output being the actual screen that
you see. Anything you do here will NOT affect the subsequent frame -
it will only affect the display of the current frame.

shader_body
{
// sample the corresponding pixel from the internal rendering canvas
// note that, here, 'uv' is undistorted.
// in the warp shader, 'uv' is warped, and 'uv_orig' is undistorted!
ret = tex2D(sampler_main, uv).xyz;

// make it a little bit "overbright"
ret *= 1.8;
}

The composite shader is easy to understand. We just sample the
internal canvas at the uv coords (undistorted here - but we could
play with them if we want!), and manipulate the result if we want
(here we brighten it a bit). The "overbrightening" here is nice because
pixels in the brighter ranges will (for display to the user only)
wash out to a white color; however, they can stay that way
for a bit. If we just displayed the color as-is here, and
instead drew our waveforms twice as bright, they would likely
start out at white but very quickly fade to shades of grey.

Note that we could do other fancy stuff here instead, like:

float2 uv_flipped = 1 - uv; // '1' auto-replicates to float2(1,1)
ret = max( tex2D(sampler_main, uv).xyz,
tex2D(sampler_main, uv_flipped).xyz );
ret = pow(ret, float3(0.5, 1, 2));

This would flip the image about its diagonal, always show you
the brighter pixel from the two orientations, and then ramp
the R/G/B channels at different exponents to create a bit of
a cepia color tone. Not too tough!

Now that you have an understanding of what the two shaders do,
let's look at all the intrinsic types and operators you can use
in shaders.

==== PIXEL SHADER REFERENCE ====
----------------------
Here is a list of all the shader functions and operations at your disposal.

Data types
----------
float 1-4 component full-precision floating-point values.
float2 Use these for most things except color values.
float3 (When working with UV coords, time values, or big ranges
float4 of values, for example.)

half 1-4 component half-precision floating-point values.
half2 Much faster on some older hardware; although drivers usually
half3 automatically substitute the 'half' type on you (behind your back)
half4 wherever it is prudent. Use 'half' for color values, or other
computations where precision is largely unimportant.

float2x2 2d transformation matrix. (Rotate and/or scale.)
float3x2 2d transformation matrix. (Rotate, scale, translation.)
float3x3 3d transformation matrix. (Rotate and/or scale.)
float4x3 3d transformation matrix. (Rotate, scale, translation.)

Operators
----------
+ - * / typical arithmetic operators.

a += b same as "a = a + b". Also valid: -= *= /=

== equality test.
< less than.
<= less than or equal to.
> greater than.
>= your mom is soo fat.

var.x swizzle operators. You can stick a dot after any variable
var.y and put up to four letters after it. If the variable is
var.z a float4, you can choose from x, y, z, and w; if it's a float2,
var.w just x and y; and so on. The data type yielded can be different
var.xy than the input, and is determined by the number of letters after
var.wzxy the dot, and which fields (from the input) you chose.
etc. For example, if you had:
float alpha = 104.37;
float2 bravo = float2(1,2);
float3 chuck = float3(10,20,30);
float4 delta = float4(5,6,7,8);
Then these swizzles would yield:
alpha.xxx -> float3(104.37, 104.37, 104.37)
bravo.yx -> float2(2,1)
chuck.z -> 30
delta.wywy -> float4(8,6,8,6)

Preprocessor
------------
If you're familiar with C/C++, you can use simple things like
#define, #if (condition) / #endif, #if / #elif/#else / #endif, and so on.

===== Intrinsic Instructions =====

Unless otherwise noted, these instructions all work on float, float2, float3,
or float4 operands.

math operations
---------------
abs(a) Absolute value. Returns max(a, -a).
frac(a) Fractional value. Returns (a - (int)a). (the part after the decimal)
floor(a) Floor. Returns ((int)a). (the part before the decimal)
Only works on single floats.
saturate(a) Clamps a to the [0..1] range. Often FREE (costs no extra instructions).
max(a,b) Returns the greater of each component between a and b.
min(a,b) Returns the lesser of each component between a and b.
sqrt(a) Returns square root of input(s). Input should be >= 0. Output always positive.
pow(a,b) Returns a^b. b can be same type as a, or just a scalar (single float).
exp(a) Returns 2^a.
log(a) Returns log2(a).
lerp(a,b,c) Linear interpolate... blends from a to b based on the value of c[0..1].
(Or extrapolates, if c is outside [0..1] range.)
a and b must be same type; can can be that same type, or just float.
Returns a + c*(b-a). Return type is same as a and b.
dot(a,b) Dot product. All versions return A SINGLE FLOAT.
dot(float a, float b) returns a+b.
dot(float2 a, float2 b) returns a.x*b.x + a.y*b.y.
dot(float3 a, float3 b) returns a.x*b.x + a.y*b.y + a.z*b.z.
dot(float4 a, float4 b) returns a.x*b.x + a.y*b.y + a.z*b.z + a.w*b.w.
lum(a) Converts a color (float3) to greyscale, or "luminance", for the human eye.
Returns dot(a, float3(0.32,0.49,0.29)).
Tip: oversaturate a color using "col = lerp(lum(col), col, 2);"
length(a) Input is float2, float3, or float4 vector; returns the length of the vector.
Returns sqrt(
normalize(a) Input is float2, float3, or float4 vector; normalizes it to unit length (1.0).
Returns a / length(a).

texture operations
------------------
tex2D(sampler_name, uv)
Samples a 2D texture at the coordinates 'uv', where UV is a float2.
Returns a float4 (r,g,b,alpha).

tex3D(sampler_name, uvw)
Samples a volume (3D) texture at the coordinates 'uvw', where UVW is a float3.
You could use this to sample a built-in "noise volume" or a volume texture
from a .DDS texture (that holds a 3D texture).
Returns a float4 (r,g,b,alpha).

GetBlur1(uv) Samples a slightly-blurred version of the main texture
(internal canvas). Input is float2; outputs (returns) a float3.
GetBlur2(uv) Samples a more-blurred version.
GetBlur3(uv) Samples a very blurry version.

mega-slow operations
--------------------
sin(a) Returns cos(a), where a is in radians. Output is in -1..1 range.
SLOW - use with care.
cos(a) Returns sin(a), where a is in radians. Output is in -1..1 range.
SLOW - use with care.
atan2(y,x) Returns the arctangent of y/x. In english, this means that if you give
it a Y and X coordinate (with the origin at zero), it will tell you
the angle you are at, with respect to the origin. The signs of x and y
are used to determine the quadrant of the return values in the range
[-pi, pi]. atan2 is well-defined for every point other than the origin.
You basically always want to use it like this:
float2 uv2 = (uv-0.5)*aspect.xy; // widescreen- or 4:3-friendly
float ang = atan2(uv2.y,uv2.x);
SLOW - use with care.
mul(a,b) Multiplies a vector and a matrix together. You can treat the matrix
as row-major or column-major based on whether you do mul(vec,mat)
or mul(mat,vec).
cross(a,b) Cross product. Returns (a.yzx*b.zxy - a.zxy*b.yzx).
Input and output must be float3's.
Slow - use with care.
if (a == b) 'If' blocks work in pixel shaders, although they can be very slow;
{ the full code is always executed, whether the branch is taken or not.
... You can use the equality operator, == (note the two equals signs!
} very important!) or the >, >=, <, or <= comparators.
else
{
...
}

Keep in mind that cos(), sin(), and atan2() are incredibly slow (~8 instructions).
Almost everything else (even divide, taking a reciprocal square root, etc.) is 1
or maybe, at most, 2 instructions.

Note that the saturate() instruction, as well as multiplying by 2, 4, or 8,
or dividing by 2, 4, or 8, is a free operation on many GPUs. And the ALUs
inside a GPU almost always do a multiply + add (both) in a single instruction.

Also, you can divide by an integer constant without suffixing it with ".0";
in C/C++, "float x = 1/5;" will give you ZERO; but in shader language, it
will give you what you expect: 0.2.

===== PER-VERTEX SHADER INPUTS =====
------------------------

Warp shader:

float2 uv; // .xy = warped UV coords, ~[0..1]
float2 uv_orig; // .xy = original (un-warped) UV coords. [0..1]
float rad; // radius of the current pixel from center of screen [0..1]
float ang; // angle of the current pixel from center of screen [0..2*PI]

Composite shader:

float2 uv; // .xy = [un-warped] UV coords.
float rad; // radius of the current pixel from center of screen [0..1]
float ang; // angle of the current pixel from center of screen [0..2*PI]
float3 hue_shader; // .xyz = a color that varies across the screen
// (the old 'hue shader' effect from MilkDrop 1).

Note that for both shaders, the vertex-interpolated angle value (ang)
gets a bit wonky near the center of the screen, where it is very difficult to
interpolate well (because it wraps suddenly from 0 to PI*2 at 9 o'clock on your
screen). If you see artifacts due to this, just use

float better_ang = atan2(uv.y - 0.5, uv.x - 0.5);

It's very slow, but will give you perfect results. Also, if you want a slightly
higher-quality value for the radius, use:

float better_rad = length(uv - 0.5);

The unwarped UV values will always be of impeccable quality, though,
because they will be interpolated in the direction that they vary,
and the rectilinear mesh is aligned perfectly for this.

===== PER-FRAME SHADER INPUTS =====

MilkDrop feeds lots of data into the the shaders. Here is a list of everything
that the shaders can access.

float4 rand_preset; // 4 random floats [0..1], updated once per preset
float4 rand_frame; // 4 random floats [0..1], updated each frame
float time; // the time, in seconds, starting at zero when the *preset* starts.
// (wraps back to zero after 10,000 seconds locked on a single preset.)
float fps; // the current framerate (frames per second).
float frame; // the current frame #.
float progress; // the progress through the current preset. [0..1]

float bass; // immediate info about audio levels,
float mid; // just like in the per-frame equations,
float treb; // etc.
float vol; //
float bass_att; // slightly dampened info about audio levels.
float mid_att; // look at bass/bass_att, for example;
float treb_att; // if it's >1, then the bass is spiking.
float vol_att; //

float4 aspect // .xy: multiplier to use on UV's to paste an image fullscreen, *aspect-aware*; .zw = inverse.
float4 texsize // info about the size of the internal canvas, in pixels.
// .xy = (width,height); .zw = (1/(float)w, 1/(float)h)

// here are some values that roam around in the [0..1] range at varying speeds.
float4 slow_roam_cos // .xyzw ~= 0.5 + 0.5*cos(time * float4(~0.005, ~0.008, ~0.013, ~0.022))
float4 roam_cos // .xyzw ~= 0.5 + 0.5*cos(time * float4(~0.3, ~1.3, ~5, ~20))
// here are the corresponding sine values, in case you want them.
// pick a cos/sin pair and use the same accessor on it (.x, .z, etc.)
// to get plot a point making a circle over time.
float4 slow_roam_sin // .xyzw ~= same, but using sin()
float4 roam_sin // .xyzw ~= same, but using sin()
// of course, if you want anything more complicated, just generate it
// yourself in the per-frame equations, save it in q1-q32, and it will
// be available to your shaders!

float q1; // The values of the q1-q32 variables,
float q2; // as output by the preset's per-frame equations.
//... //
float q31; //
float q32; //

float4 _qa; // q1-q4 The values of the q1-q32 variables,
float4 _qb; // q5-q8 grouped into float4's
float4 _qc; // q9-q12 for more convenient access.
float4 _qd; // q13-q16
float4 _qe; // q17-q20
float4 _qf; // q21-q24
float4 _qg; // q25-q28
float4 _qh; // q29-q32

float blur1_min // these are the values of the min/max
float blur1_max // allowable color values for the 3 blur passes,
float blur2_min // as set from the onscreen menus.
float blur2_max // more info below.
float blur3_min //
float blur3_max //

// note/warning: in general, don't use the current time value
// as an input to the *dynamic* rotations; as time gets large,
// the results will become total chaos.
float4x3 rot_s1; // four random, static rotations.
float4x3 rot_s2; // randomized @ preset load time.
float4x3 rot_s3; // minor translation component (<1).
float4x3 rot_s4;

float4x3 rot_d1; // four random, slowly changing rotations.
float4x3 rot_d2;
float4x3 rot_d3;
float4x3 rot_d4;

float4x3 rot_f1; // faster-changing.
float4x3 rot_f2;
float4x3 rot_f3;
float4x3 rot_f4;

float4x3 rot_vf1; // very-fast-changing.
float4x3 rot_vf2;
float4x3 rot_vf3;
float4x3 rot_vf4;

float4x3 rot_uf1; // ultra-fast-changing.
float4x3 rot_uf2;
float4x3 rot_uf3;
float4x3 rot_uf4;

float4x3 rot_rand1; // random every frame
float4x3 rot_rand2;
float4x3 rot_rand3;
float4x3 rot_rand4;

==== TEXTURE SAMPLING ====
We've already used one texture: the internal canvas, also called "Main".
Because it's always being used, you don't have to declare it. You can
just sample it. However, you have some options for how to sample it.
There are four samplers tied to the Main canvas:

BEHAVIOR OUTSIDE
SAMPLER NAME FILTERING METHOD [0..1] UV RANGE
------------ ---------------- ----------------
sampler_fw_main* bilinear filtering wrap
sampler_fc_main bilinear filtering clamp
sampler_pw_main point sampling wrap
sampler_pc_main point sampling clamp

* you can also just use "sampler_main" for this one,
since it's by far the most common.

When you go to sample a texture, the GPU finds the exact spot
in the texture that the UV coordinates point to. The chances
are good that it falls in between 4 texels (pixels) rather than
perfectly on one of them. If you use bilinear filtering to
sample, it will return a properly-weighted average of the four
pixels. If you use point sampling, it will just return the
nearest single pixel (also called "nearest neighbor").

Wrap vs. clamp is also pretty simple: if you specify a UV coord
of float2(-0.1, 0.5), the wrap mode would map this to (0.9, 0.5),
while the clamp mode would clamp it at (0.0, 0.5). Wrap mode
tends to create tiled images, while clamp mode takes the border
color and extends it out infinitely.

In general, other textures can be sampled similarly, using these
same two-letter prefixes ("_fw", "_pc", etc.). Or, you can
always just leave off the prefix, and MilkDrop will assume you
want to do "_fw" - bilinear filtering and wrap mode - the defaults.

===== MILKDROP'S BUILT-IN TEXTURES - MAIN, BLUR, and NOISE =====
MilkDrop has several built-in textures you can sample from.

MAIN
----
First, there is the Main texture (the internal canvas). As already
mentioned, you can sample from it by using sampler_main or one
of its variants.

===== BLUR1, BLUR2, BLUR3 =====

Next, there are several blurred versions of the main texture.
These are called Blur1, Blur2, and Blur3. Each one is
progressively blurrier. You can access them using these special
functions:

GetBlur1(uv) // these take a float2 as input
GetBlur2(uv) // & return a float3 color value
GetBlur3(uv)

GetBlur1 returns a slightly blurred image, GetBlur2 a more blurry image,
and GetBlur3 an extremely blurry image. A call to one of the GetBlur
functions is very fast, but keep in mind that the blur textures are only
generated each frame if the shaders actually use them, and the results
find their way into the final output color value of the pixel shader!
Blur1 is the fastest to generate; then Blur2 (because it is generated
from Blur1); and finally, Blur3 is the slowest (generated from Blur2).

Here is an example of how to use one:

float3 blurry = GetBlur2(uv);

You could add this to your sample from the Main texture to
produce a softer-looking image, for example. Or, you could
do an edge detect in the composite shader, by taking the
[absolute value of the] difference between the crisp and blurred
main textures:

float3 crisp = tex2D(sampler_main, uv).xyz;
float3 blurry = GetBlur1(uv);
ret = abs( crisp - blurry )*4;

The "skin dots" effect in some of the presets (it makes spots
and stripes like you might see on fish or leopards, in nature)
is based on a very mild edge-detect in the *warp* shader,
and uses it to enforce a certain amount of variance in the
color values. It also serves to break up large areas of solid
white pixels.

Note that you can do some cool glow effects by raising the
"min" values above 0. Say, for example, you set blur1_min
to 0.5. That means that any pixels with color values below
0.5 will get clipped to 0.5. So, when you call GetBlur1(),
it's going to give you values in the range [0.5 .. 1.0].
However, because you were only using half the range of possible
values, the precision of these values will be twice as good.
That's the purpose of the min/max values. Watch out, though -
having your values clipped to a minimum of 0.5 would look bad
if you actually had colors that are over 0.5, and you're not
subtracting that 0.5 off.

However, if you do set a min and then subtract it off, you can
also get some great glow effects, where only really
bright pixels contribute to the "glow" If you set the min to
0.7, for example, and then sample like this:

ret += (GetBlur1(uv) - blur1_min)*2;

It will subtract off the 0.7 minimum threshold, but because
of the clipping, you will basically just see the bright
pixels "glowing". The *2 is just for a little extra glow.

===== NOISE TEXTURES =====

There are also "noise" (random value) textures built in to MilkDrop.
They are generated when MilkDrop starts, but only so the large amount
of (random) data wouldn't bloat the size of the MilkDrop download.
They vary in the quality (smoothness) of the noise, as well as
how often the pattern repeats itself. Always use the smallest
possible noise texture (_lite or _lq versions) when possible.

Here are the details on the six textures:

NAME DIMS PIXELS QUALITY
---- ---- ------ ---------
noise_lq 2D 256x256 low
noise_lq_lite 2D 32x32 low
noise_mq 2D 64x64 medium
noise_hq 2D 32x32 high
noisevol_lq 3D 32x32x32 low
noisevol_hq 3D 8x8x8 high

Notice that four of them are two-dimensional (use tex2D(float2 uv)
to sample them), and two of them are three-dimensional (use
tex3D(float3 uvw) to sample them).

They come in at various sizes. You should always use the smallest
one necessary, to be video memory cache-friendly!

The _lq, _mq, and _hq suffixes denote low, medium, or high quality.
The _lq textures have one random value at every texel in the
texture. But the _mq textures have (generally) about four texels
per random value, with high-quality [cubic] filtering baked into the
texture. (Sometimes you just want something better than bilinear
filtering, you know?) The high-quality textures usually have about
8 texels for every random value. The sizes given here, in pixels,
are actually abstractions - they are the conceptual # of pixels
(values) before repetition. In reality, the textures are bigger
(for medium & high quality), and the extra texels are all filled
in using high-quality interpolation.

The higher-quality textures aren't any slower to use, as long as
you're sampling them at the right frequency. If you sample any
of these at too high a frequency (i.e. tile them like crazy /
multiply the UV's by a large number) your video memory texture
cache will bring your GPU to a grinding halt. Don't do it!

If using Noise textures with the default sampler settings (filtering
and wrap), you don't need to declare them above the shader_body; they
are always available. However, if you want to sample them with
special options (clamping or point sampling), then you do have to.
(ex: "sampler sampler_fc_noise_lq", or "sampler_pw_noise_lq").

To sample a color value from a noise texture, add code like this:

float4 noiseVal = tex2D(sampler_noise_lq, uv_orig );

This returns a float4 of values in the [0..1] range. However, the noise
image will be stretched up so the 64x64 pixels cover the screen. What we'd
really like is to tile it so the noise values map 1:1 to pixels on the
screen.

To do this, we need to invoke another handy feature: you can fetch the size
of any texture in MilkDrop. Just declare a float4 (still outside the shader
body) with the name of the texture, preceded by "texsize_" - like this:

float4 texsize_noise_lq; // .xy = (w,h); .zw = (1/(float)w, 1/(float)h)

Also, recall that the size of the Main canvas is universally available to
all shaders, and looks like this: (this is auto-declared for you, by the way)

float4 texsize // .xy = (w,h); .zw = (1/(float)w, 1/(float)h)

So, if we change our sampling code to look like this:

float4 noiseVal = tex2D(sampler_noise_lq, uv_orig*texsize.xy*texsize_noise_lq.zw );

It's going to do exactly that. This is a very common and useful technique.
uv_orig gives you the original (unwarped)
UV coordinates [0..1]. If we then multiply by texsize.xy, we get the
pixel number we are on. For example, if the screen was 1280 x 1024 pixels,
we'd get float2 in the range [0..1279, 0..1023]. If we then multiply by
texsize_noise_lq.zw, we're dividing by the size of the noise texture,
in pixels (this one is 256x256). So, we'd end up with UV coords roughly
in the range [0..5, 0..4] - our image has been perfect tiled onto the
screen, with the pixels displaying 1:1.

This can be used to mix a bit of random noise into the image each frame,
which can increase image quality - it's similar to error diffusion
dithering (which is one of the things that set the original Geiss
plugin/screensaver apart from the others, image-quality wise!). You
can ponder the reasons why. Also, further adding "rand_frame.xy" to the
UV coords will reposition the noise values every frame, making it seem
like truly random [changing] noise:

float2 noise_uv = uv_orig*texsize.xy*texsize_noise_lq.zw + rand_frame.xy;
float4 noiseVal = tex2D(sampler_noise_lq, noise_uv);

To add random dithering (which, statistically, is the same as error-
diffusion dithering), try this:

float2 uv_noise = uv_orig*texsize.xy*texsize_noise_lq.zw + rand_frame.xy;
half4 noiseVal = tex2D(sampler_noise_lq, uv_noise);
ret = tex2D(sampler_main, uv);
ret += (noiseVal.xyz*2-1) * 0.01;

This will add a good deal of noise into the image each frame. Adding
'rand_frame.xy' to the UV coordinate serves to randomly place
the noise texture each frame, preventing the noise imprint from being
exactly the same each frame, which would cause artifact buildup.

Important: Note that the medium- and high-quality textures should never be
used for 1:1 mapping! - it is a huge waste. You will only benefit from their
higher quality if you are *zoomed in* on these textures, seeing them
magnified, sampling them at a low frequency. If they are minified
(sampled at a high frequency / zoomed out of) or even displayed at 1:1,
you will thrash your video memory cache and the preset will run very
slow.

===== READING TEXTURES FROM DISK =====

Declaring and sampling from your own textures is easy. First,
create your texture. If you plan on sharing your presets with
other people, please make your texture SMALL (256x256 or less)
and save it as a JPG file at 95% quality. The file size should
be between 10k and 50k (kilobytes). Of course, the textures
could be huge, crisp photos if you want - they will just be
heavy (to send to other people) and will cause a little delay
when you switch to a preset that uses them (and loads the texture).

Save the texture to the folder:

c:\program files\winamp\plugins\milkdrop2\textures

or wherever you installed Winamp and MilkDrop to. Let's imagine
you called your texture billy.jpg.

Then, in any shader, above the shader_body section, declare a sampler
for the texture:

sampler sampler_billy;

That's all you have to do. It will find the file (billy.jpg)
and load it. Note that the sampler name DOES have to start with
"sampler_", and if you want, you could prefix it with "sampler_pc_"
or "sampler_fw_" (or whatever) to turn on texture clamp and/or point
sampling.

Texture formats supported include: [in order of priority]

jpg (great compression)
dds (a microsoft/directx format - very flexible - can even do 3D)
png (portable network graphics; can give you compress w/an alpha channel)
tga (truevision Targa - 1, 3, or 4 channels)
bmp (puke)
dib (puke)

Now that you've declared the texture, you can sample it like this,
from within the shader_body section:

float3 mypixel = tex2D(sampler_billy, uv2).xyz;

So first it will try to find billy.jpg; then billy.dds; and so
on, until it finds a valid texture. If the texture can not be
found in the "milkdrop2\textures" directory, it will then also try
to find it **in the current preset directory**; this is done so that
preset downloaders can be lazy and just put the presets, along
with the textures that come with them, into the same directory.

If your shader wants to know how big the texture is, declare this
(also above the shader_body section):

float4 texsize_billy; // .xy = (w,h); .zw = (1/w, 1/h)

MilkDrop will see the "texsize_" prefix and automatically know what
to do. (You don't have to include the //comment, of course.)

To stretch this texture to cover the screen, do this (in the shader
body):

ret = tex2D(sampler_billy, uv).xyz;

Or to map it fitted to the screen, aspect-aware:

ret = tex2D(sampler_billy, uv * aspect.xy).xyz;

Or to tile it so the pixels are represented 1:1:

ret = tex2D(sampler_billy, uv * texsize.xy * texsize_billy.zw).xyz;

Or to map it tiled exactly 5 times:

ret = tex2D(sampler_billy, uv * 5).xyz;

Or to zoom into the center 20% of the image:

ret = tex2D(sampler_billy, (uv-0.5)*0.2 + 0.5 ).xyz;

Of course, you could also declare sampler_pw_billy, to do point
sampling, or sampler_fc_billy, for clamping, and so on.

===== RANDOM TEXTURE SELECTION =====
------------------------
You can also load in a random texture. Just use the name "rand00"
through "rand15" as the filename, and MilkDrop will pick a random
file and do the rest. The texsize_ parameters work too. For example:

sampler sampler_rand07;
float4 texsize_rand07;

shader_body
{
...
float3 color = tex2D(sampler_rand07, uv);
...
}

You can also choose from random subsets of textures on disk! Say you
have a whole slew of random textures in your textures\ subdirectory,
but you have a subset in there that begin with the word "smalltiled".
If you specify:

sampler sampler_rand02_smalltiled;
float4 texsize_rand02; // ...it's smart enough to get it from just this.

shader_body
{
...
float3 color = tex2D(sampler_rand07_smalltiled, uv);
...
}

Then every time the preset loads (or the shader is recompiled), it's
going to pick a new random texture, but it will choose only from the
subset of those textures whose names begin with "smalltiled".

One last thing, a tip: if you are working in windowed mode (or multimon)
and added textures to the directory and haven't yet exited the plugin,
to force the list of textures to update itself, edit one of the shaders
(any shader) and then hit CTRL+ENTER (accept). That will trigger it
to rescan the directory (but only if it needs to, because your shaders
ask for random textures).

==== MISC. COOL SHADER TRICKS ====

AUTO CENTER DARKENING

MilkDrop 1 had a cool feature, "center darken", that would quickly dampen
bright pixels placed at the center of the screen, because in "zoomy"
(forward motion) presets, the screen would quickly become all white
if you didn't. As presets get more sophisticated, though, where the
"center" of the zooming motion is can be very hard to pinpoint.

You can actually find it algorithmically. Wherever on the screen you
have warped UV coordinates that are very close to the original UV
coordinates, it means there's either no motion there, or it's the
center of motion - you'll know, based on what kind of preset you're
writing. If it's a "zoomy" preset, it's probably the latter. In this
case, just use something like this in your warp shader:

// this darkens the pixels at the center of the zoom, only
ret *= 0.97 + 0.03*saturate( length(uv - uv_orig)*200 );

RANDOM DIFFUSION DITHER

See above, in the "noise" section.

SOFT MAX

The max(a,b) function returns the max. value for each channel
of the two inputs, however, this can have a discontinuous
look sometimes, as it switches from a to b or back suddenly.
If you want a not-so-accurate, but smoother, max function,
try this:

a + b - a*b

Note that the inputs must be in the [0..1] range.

==== QUALITY ASSURANCE FOR SHADERS ====

<nowiki>*Please*</nowiki> adhere to these guidelines when writing shaders...
# use small (256x256 or less) textures; save as jpg 95% so your presets are small to download, and so they load w/o a pause.
# make sure your shaders are zippy.
#* avoid 'if' statements.
#* avoid "massive zoom-outs" of any texture. Sampling textures at too high a frequency thrashes your texture cache and will drop your framerate like mad. Sample things near 1:1, or feel free to zoom in close on them, but avoid extreme zoom-outs.
#* avoid sin() and cos() functions if you can. If their inputs don't vary from pixel to pixel, calculate the sin/cos values in the per-frame equations, then store them in q1-q32, and read them into your shader from there.
#* any calculation that results in the same value for all pixels on the screen should be offloaded into MilkDrop's per-frame equations, then passed to the shader via the q1-q32 variables. These variables are directly accessible from all shaders (q1, q2, etc.) and can also be read in as float4's for convenience (q1-q4 make up a float4 called _qa; q5-q8 come together in _qb; etc.).
#* also avoid doing motion/warping calculations in the warp shader, that you could do in the per-vertex equations. Those run on the CPU, which is a huge resource that is almost never completely used; the GPU, although processing 1,000 times as much math because it works per-pixel instead of per-vertex, can use as much of a break as it can get. Any low-frequency effects (values that vary slowly over the screen) should go in the per-vertex equations, and only the high-frequency component of the motion or warping should come from the pixel shader.
#* keep in mind that the DirectX shader compiler is superb at optimizing; anything that can be thrown out, will be. Things like
ret *= 1.0;
ret += 0;
ret += tex2D(mytex, uv).xyz * 0;
will completely disappear. If you sample a texture and then the
sample doesn't end up making it into the final output color value,
the texture will never even get bound (or loaded from disk),
let alone sampled. And so on.
#* you can use the 'half' type wherever you don't need full 'float'
precision. Generally use 'float' for UVs and time values, and
'half' for almost everything else. However, don't stress about it
too much, because most GPUs run
everything at full-precision & full-speed nowadays - and for the
older GPUs that don't, the driver is probably very smart (if it's
an Nvidia or ATI card) about auto-substituting halfs for floats
wherever possible.
# before sharing your presets, please make sure they look good in a
SQUARE or WIDESCREEN window. If they don't, scan these guidelines
and you will probably be able to easily fix it.

The overall design goal in MilkDrop, concerning aspect ratio, is to
fit the preset to the long axis of the window, and to crop the rest,
but to do all of this without any stretching or zooming (so all internal
canvas pixels map 1:1 to screen pixels).

-per-frame/per-vertex equations:
* multiply XY coords by the values "aspectx" and "aspecty", respectively.

-shader code:
* multiply UV coordinates by 'aspect.xy', prior to using them
to sample a texture, to make the texture fit on the screen properly.
(For example, if the screen is wide, the image will be fitted to cover
the width of the screen, and it will be cropped at the top and bottom.)

* multiply by 'aspect.zw' to make it fit the other way (it will fit
the image to be completely visible in one dimension, and tiled in the
other direction).

* any time you perturb the UV coordinates in the warp shader, prior to
sampling the Main texture, you should multiply the "delta" you are applying
by aspect.xy. Otherwise, in a widescreen window, the "delta" will actually
be dramatically squished, or in a tall window, the change would be
elongated very vertically.

* the 'ang' value is aspect-aware, in the per-vertex equations, as well
as in the warp and composite shaders. However, if you generate your own
high-quality "ang" value using atan2(), beware - you really
should multiply the UV's by aspect.xy beforehand, like this:
float2 uv2 = (uv-0.5)*aspect.xy;
float ang = atan2(uv2.y,uv2.x);

=== QUALITY ASSURANCE ===
When designing presets, please adhere to the pixel shader 'quality assurance'
guidelines in the above section, as they are very important. But, in order
to make sure the presets you create work well on other systems, please
also keep in mind:

# Keep your presets fast. There's nothing to spoil the mood like a preset popping up that chokes at 10 fps. Since division is 11 times slower than multiplication (or addition/subtraction), if you divide a bunch of values by one other value, pre-divide that value ("inv = 1/myval;") and then multiply those other values by that inverse. Also, never put computations in the per-vertex code that are the same for every pixel; move these into the per-frame code, and carry the results to the per-vertex code using the q1-q32 variables. Remember that maxim: "If a per-vertex equation doesn't use at least one of the variables { x, y, rad, ang }, then it should be actually be a per-frame equation."
# Design your presets using the default mesh size option from the config panel, or at least check, before you distribute them, to make sure they look correct at the default mesh size. If your mesh is too coarse (small), then a viewer with the default mesh size might see unexpected "bonus" effects that you might not have intended, and might mess up your preset. If your mesh is too fine, then a viewer with the default might not see all the detail you intended, and it might look bad.
# Try to design your presets in a 32-bit video mode, so that its brightness levels are standard. The thing to really watch out for is designing your presets in 16-bit color when the "fix pink/white color saturation artifact" checkbox is checked. checkbox keeps the image extra dark to avoid color saturation, which is only necessary on some cards, in 16-bit color. If this is the case for you, and you write a preset, then when you run it on another machine, it might appear insanely bright.
# Don't underestimate the power of the 'dx' and 'dy' parameters (in the per-vertex equations). Some of the best presets are based on using these. If you strip everything out of a preset so that there's no motion at all, then you can use the dx and dy parameters to have precise manual control over the motion. Basically, all the other effects (zoom, warp, rot, etc.) are just complicated abstractions; they could all be simulated by using only { x, y, rad, ang } and { dx, dy }.
# If you use the 'progress' variable in a preset, make sure you try the preset out with several values for 'Time Between Auto Preset Changes'. The biggest thing to avoid is using something like sin(progress), since the rate at which 'progress' increases can vary drastically from system to system, dependong on the user's setting for 'Time Between Auto Preset Changes'.
# if writing shaders, please also see the 'Quality Assurance for Shaders' section above.

=== DEBUGGING ===
One feature that preset authors should definitely be aware of is the variable monitoring feature, which lets you monitor (watch) the value of any per-frame variable you like. First, hit the 'N' key to show the monitor value, which will probably display zero. Then all you have to do is add a line like this to the per-frame equations:

monitor = x;

where 'x' is the variable or expression you want to monitor. Once you hit CTRL+ENTER to accept the changes, you should see the value of the per-frame variable or expression in the upper-right corner of the screen!

Once again, note that it only works for *per-frame* equations, and NOT for per-vertex equations.

=== FUNCTION REFERENCE ===
Following is a list of the functions supported by the expression evaluator (for preset init, per-frame, and per-vertex equations; NOT for pixel shaders). The list was blatently ripped from the help box of Justin Frankel's AVS plug-in, since MilkDrop uses the expression evaluator that he wrote.

Format your expressions using a semicolon (;) to delimit between statements.
Use parenthesis ['(' and ')'] to denote precedence if you are unsure.
The following operators are available:
= : assign
+,-,/,* : plus, minus, divide, multiply
| : convert to integer, and do bitwise or
& : convert to integer, and do bitwise and
% : convert to integer, and get remainder
The following functions are available:
int(var) : returns the integer value of 'var' (rounds toward zero)
abs(var) : returns the absolute value of var
sin(var) : returns the sine of the angle var (expressed in radians)
cos(var) : returns the cosine of the angle var
tan(var) : returns the tangent of the angle var
asin(var) : returns the arcsine of var
acos(var) : returns the arccosine of var
atan(var) : returns the arctangent of var
sqr(var) : returns the square of var
sqrt(var) : returns the square root of var
pow(var,var2) : returns var to the power of var2
log(var) : returns the log base e of var
log10(var) : returns the log base 10 of var
sign(var) : returns the sign of var or 0
min(var,var2) : returns the smalest value
max(var,var2) : returns the greatest value
sigmoid(var,var2) : returns sigmoid function value of x=var (var2=constraint)
rand(var) : returns a random integer modulo 'var'; e.g. rand(4) will return 0, 1, 2, or 3.
bor(var,var2) : boolean or, returns 1 if var or var2 is != 0
bnot(var) : boolean not, returns 1 if var == 0 or 0 if var != 0
if(cond,vartrue,varfalse) : if condition is nonzero, returns valtrue, otherwise returns valfalse
equal(var,var2) : returns 1 if var = var2, else 0
above(var,var2) : returns 1 if var > var2, else 0
below(var,var2) : returns 1 if var < var2, else 0

return to top
return to milkdrop.html

Media Library API

2008-09-25T13:05:23Z

Tarik: Protected "Media Library API" [edit=autoconfirmed:move=autoconfirmed]

== Messages sent to your plugin's MessageProc ==
<source lang="cpp">
// return values from the winampUninstallPlugin(HINSTANCE hdll, HWND parent, int param)
// which determine if we can uninstall the plugin immediately or on winamp restart
//
// uninstall support was added from 5.0+ and uninstall now support from 5.5+
// it is down to you to ensure that if uninstall now is returned that it will not cause a crash
// (ie don't use if you've been subclassing the main window)
#define ML_PLUGIN_UNINSTALL_NOW 0x1
#define ML_PLUGIN_UNINSTALL_REBOOT 0x0

// messages your plugin may receive on MessageProc()

#define ML_MSG_TREE_BEGIN 0x100
#define ML_MSG_TREE_ONCREATEVIEW 0x100 // param1 = param of tree item, param2 is HWND of parent. return HWND if it is us

#define ML_MSG_TREE_ONCLICK 0x101 // param1 = param of tree item, param2 = action type (below), param3 = HWND of main window
#define ML_ACTION_RCLICK 0 // return value should be nonzero if ours
#define ML_ACTION_DBLCLICK 1
#define ML_ACTION_ENTER 2
#define ML_ACTION_LCLICK 3

#define ML_MSG_TREE_ONDROPTARGET 0x102 // param1 = param of tree item, param2 = type of drop (ML_TYPE_*), param3 = pointer to data (or NULL if querying).
// return -1 if not allowed, 1 if allowed, or 0 if not our tree item

#define ML_MSG_TREE_ONDRAG 0x103 // param1 = param of tree item, param2 = POINT * to the mouse position, and param3 = (int *) to the type
// set *(int*)param3 to the ML_TYPE you want and return 1, if you support drag&drop, or -1 to prevent d&d.

#define ML_MSG_TREE_ONDROP 0x104 // param1 = param of tree item, param2 = POINT * to the mouse position
// if you support dropping, send the appropriate ML_IPC_HANDLEDROP using SendMessage() and return 1, otherwise return -1.

#define ML_MSG_TREE_ONKEYDOWN 0x105 // Send when key pressed
// param1 = param of tree item;
// param2 = pointer to NMTVKEYDOWN
// param3 = tree hwnd
// return 0 if it's not yours, 1 if it is

#define ML_MSG_TREE_END 0x1FF // end of tree specific messages

#define ML_MSG_ONSENDTOBUILD 0x300 // you get sent this when the sendto menu gets built
// param1 = type of source, param2 param to pass as context to ML_IPC_ADDTOSENDTO
// be sure to return 0 to allow other plugins to add their context menus

// if your sendto item is selected, you will get this with your param3 == your user32 (preferably some
// unique identifier (like your plugin message proc). See ML_IPC_ADDTOSENDTO
#define ML_MSG_ONSENDTOSELECT 0x301
// param1 = type of source, param2 = data, param3 = user32

// return TRUE and do a config dialog using param1 as a HWND parent for this one
#define ML_MSG_CONFIG 0x400

</source>

== Messages you can send to the Media Library HWND ==
<source lang="cpp">

#define ML_TYPE_UNKNOWN -1
#define ML_TYPE_ITEMRECORDLIST 0 // if this, cast obj to itemRecordList
#define ML_TYPE_FILENAMES 1 // double NULL terminated char * to files, URLS, or playlists
#define ML_TYPE_STREAMNAMES 2 // double NULL terminated char * to URLS, or playlists ( effectively the same as ML_TYPE_FILENAMES, but not for files)
#define ML_TYPE_CDTRACKS 3 // if this, cast obj to itemRecordList (CD tracks) -- filenames should be cda://<drive letter>,<track index>. artist/album/title might be valid (CDDB)
#define ML_TYPE_QUERYSTRING 4 // char * to a query string
#define ML_TYPE_PLAYLIST 5 // mlPlaylist *
#define ML_TYPE_ITEMRECORDLISTW 6 // if this, cast obj to itemRecordListW
// added from 5.36+
#define ML_TYPE_FILENAMESW 7 // double NULL terminated wchar_t * to files, URLS, or playlists
#define ML_TYPE_STREAMNAMESW 8 // double NULL terminated wchar_t * to URLS, or playlists ( effectively the same as ML_TYPE_FILENAMESW, but not for files)
#define ML_TYPE_PLAYLISTS 9 // mlPlaylist **, null terminated
#define ML_TYPE_TREEITEM 69 // uhh?

typedef struct
{
const wchar_t *filename;
const wchar_t *title;
// only fill in the following two if already know. don't calculate it just for the struct.
// put -1 for "don't know"
int numItems;
int length; // in seconds.
} mlPlaylist;

// if you wish to put your tree items under "devices", use this constant for ML_IPC_ADDTREEITEM
#define ML_TREEVIEW_ID_DEVICES 10000

// children communicate back to the media library by SendMessage(plugin.hwndLibraryParent,WM_ML_IPC,param,ML_IPC_X);
#define WM_ML_IPC WM_USER+0x1000

#define ML_IPC_GETCURRENTVIEW 0x090 // Returns HWND to the currently selected view or NULL if nothing selected or error. (WA 5.22 and higher)

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Old Tree Item API (deprecated)
//
#define ML_IPC_ADDTREEITEM 0x0101 // pass mlAddTreeItemStruct as the param
#define ML_IPC_SETTREEITEM 0x0102 // pass mlAddTreeItemStruct with id valid
#define ML_IPC_DELTREEITEM 0x0103 // pass param of tree item to remove
#define ML_IPC_GETCURTREEITEM 0x0104 // returns current tree item param or 0 if none
#define ML_IPC_SETCURTREEITEM 0x0105 // selects the tree item passed, returns 1 if found, 0 if not
#define ML_IPC_GETTREE 0x0106 // returns a HMENU with all the tree items. the caller needs to delete the returned handle! pass mlGetTreeStruct as the param

/* deprecated. Use MLTREEITEM instead */
typedef struct {
INT_PTR parent_id; //0=root, or ML_TREEVIEW_ID_*
char *title;
int has_children;
INT_PTR this_id; //filled in by the library on ML_IPC_ADDTREEITEM
} mlAddTreeItemStruct;

typedef struct {
int item_start; // TREE_PLAYLISTS, TREE_DEVICES...
int cmd_offset; // menu command offset if you need to make a command proxy, 0 otherwise
int max_numitems; // maximum number of items you wish to insert or -1 for no limit
} mlGetTreeStruct;

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// For Predixis, with Love
/// deprecatded (never use!!!)
///
#define ML_IPC_ADDTREEITEM_EX 0x0111 // pass mlAddTreeItemStructEx as the param
#define ML_IPC_SETTREEITEM_EX 0x0112 // pass mlAddTreeItemStructEx with this_id valid

typedef struct {
INT_PTR parent_id; //0=root, or ML_TREEVIEW_ID_*
char *title;
int has_children;
INT_PTR this_id; //filled in by the library on ML_IPC_ADDTREEITEM
int imageIndex; // index of the image you want to be associated with your item
} mlAddTreeItemStructEx;

/// deprecatded (never use!!!)
#define ML_IPC_ADDTREEIMAGE 0x110 // adds tree image to the ml. Use mlAddTreeImageStruct as the param.
/// end of predixis special

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Tree Item API (starting from 5.3)
//
#define ML_IPC_TREEITEM_GETHANDLE 0x120 // Gives you HANDLE to the item with specified ID in the param
#define ML_IPC_TREEITEM_GETCHILD 0x121 // Returns HANDLE to the child item for the item HANDLE specified as a param.
#define ML_IPC_TREEITEM_GETNEXT 0x122 // Returns HANDLE to the next item for the item HANDLE specified as a param.
#define ML_IPC_TREEITEM_GETSELECTED 0x123 // Returns HANDLE to selected item.
#define ML_IPC_TREEITEM_GETINFO 0x124 // Pass MLTREEITEMINFO as a param. return TRUE - if ok
#define ML_IPC_TREEITEM_SETINFO 0x125 // Pass MLTREEITEMINFO as a param. return TRUE - if ok
#define ML_IPC_TREEITEM_ADD 0x126 // Adds new item using MLTREEITEM passed as a param
#define ML_IPC_TREEITEM_DELETE 0x127 // Deletes tree item. Pass HANDLE as a param.
#define ML_IPC_TREEITEM_SELECT 0x128 // Selects tree item. Pass HANDLE as a param.
#define ML_IPC_TREEITEM_GETROOT 0x129 // Gets first item.
#define ML_IPC_TREEITEM_INSERT 0x130 // like ML_IPC_TREEITEM_ADD, but id becomes an "insert after" ID
#define ML_IPC_TREEITEM_GETCHILD_ID 0x131 // Returns ID to the child item for the item ID specified as a param.
#define ML_IPC_TREEITEM_GETNEXT_ID 0x132 // Returns ID to the next item for the item ID specified as a param.
#define ML_IPC_TREEITEM_ADDW 0x133 // Adds new item using MLTREEITEMW passed as a param
#define ML_IPC_TREEITEM_INSERTW 0x134 // like ML_IPC_TREEITEM_ADDW, but id becomes an "insert after" ID
#define ML_IPC_TREEITEM_SETINFOW 0x135 // Pass MLTREEITEMINFOW as a param. return TRUE - if ok
#define ML_IPC_TREEITEM_GETINFOW 0x136 // Pass MLTREEITEMINFO as a param. return TRUE - if ok
#define MLTI_ROOT (INT_PTR)TVI_ROOT // can be used in ML_IPC_TREEITEM_GETCHILD

typedef struct {
size_t size; // size of this struct
UINT_PTR id; // depends on contxext
UINT_PTR parentId; // 0 = root, or ML_TREEVIEW_ID_*
char *title; // pointer to the buffer contained item name.
size_t titleLen; // used for GetInfo
BOOL hasChildren; // TRUE - has children
int imageIndex; // index of the associated image
} MLTREEITEM;

typedef struct {
MLTREEITEM item; // item data
UINT mask; // one or more of MLTI_* flags
UINT_PTR handle; // Handle to the item. If handle is NULL item->id will be used
} MLTREEITEMINFO;

typedef struct {
size_t size; // size of this struct
UINT_PTR id; // depends on context
UINT_PTR parentId; // 0 = root, or ML_TREEVIEW_ID_*
wchar_t *title; // pointer to the buffer contained item name.
size_t titleLen; // used for GetInfo
BOOL hasChildren; // TRUE - has children
int imageIndex; // index of the associated image
} MLTREEITEMW;

typedef struct {
MLTREEITEMW item; // item data
UINT mask; // one or more of MLTI_* flags
UINT_PTR handle; // Handle to the item. If handle is NULL item->id will be used
} MLTREEITEMINFOW;
// Flags that used in the MLTREEITEMINFO struct
#define MLTI_CHILDREN TVIF_CHILDREN
#define MLTI_IMAGE TVIF_IMAGE
#define MLTI_TEXT TVIF_TEXT
#define MLTI_ID TVIF_PARAM

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Tree image (starting from 5.3)
//

#define ML_IPC_TREEIMAGE_ADD 0x140 // adds tree image to the ml. Use MLTREEIMAGE as the param.

typedef struct _COLOR24
{
unsigned char rgbBlue;
unsigned char rgbGreen;
unsigned char rgbRed;
}COLOR24; // color struct

typedef void (*BMPFILTERPROC)(const COLOR24*, const COLOR24*, COLOR24*); // color filter procedure
// you got two colors: color1 and color2 (usualy BG and FG colors) also you as a third parameter
// you get a pixel color value that you need (can) modify

#define FILTER_NO ((BMPFILTERPROC)NULL)
#define FILTER_DEFAULT1 ((BMPFILTERPROC)1)
#define FILTER_DEFAULT2 ((BMPFILTERPROC)2)

#define MLTREEIMAGE_NONE 0
#define MLTREEIMAGE_DEFAULT 1
#define MLTREEIMAGE_BRANCH 2 // calculates at the time
#define MLTREEIMAGE_BRANCH_EXPANDED 3
#define MLTREEIMAGE_BRANCH_COLLAPSED 4
#define MLTREEIMAGE_BRANCH_NOCHILD 5

typedef struct {
HINSTANCE hinst; // hInstance
int resourceId; // resource id
int imageIndex; // set image to specified index (specify -1 to get a new index back)
BMPFILTERPROC filterProc; // pointer to the filter proc to use or one of the FILTER_*
int width; // reserved
int height; // reserved
} MLTREEIMAGE; // basicly ml will read your reosurce when it will need to create your image

#define ML_IPC_NEWPLAYLIST 0x107 // pass hwnd for dialog parent as param
#define ML_IPC_IMPORTPLAYLIST 0x108 // pass hwnd for dialog parent as param
#define ML_IPC_IMPORTCURRENTPLAYLIST 0x109
#define ML_IPC_GETPLAYLISTWND 0x10A
#define ML_IPC_SAVEPLAYLIST 0x10B // pass hwnd for dialog parent as param
#define ML_IPC_OPENPREFS 0x10C

#define ML_IPC_PLAY_PLAYLIST 0x010D // plays the playlist pointed to by the tree item passed, returns 1 if found, 0 if not
#define ML_IPC_LOAD_PLAYLIST 0x010E // loads the playlist pointed to by the tree item passed into the playlist editor, returns 1 if found, 0 if not

#define ML_IPC_REFRESH_PREFS 0x10F // this doesn't belong in here

/** ------------------
** ml_playlists
** ------------------ */

#define PL_FLAG_SHOW 1
#define PL_FLAG_SWITCH 2
#define PL_FLAGS_IMPORT 4 // set to have ml_playlists make a copy (only valid for mlAddPlaylist)
#define PL_FLAG_FILL_FILENAME 8 // only valid for mlMakePlaylist

typedef struct
{
size_t size; // size of this struct
const wchar_t *playlistName; // set to NULL (or empty string) to prompt the user for a name
const wchar_t *filename;
int flags; // see PL_FLAG_* above
// the following two items can be optionally filled in (set to -1 otherwise)
// if they aren't set, the playlist file will have to be opened and parsed
// so prepopulating is faster (assuming if you already know the data)
int numItems; // set to -1 if you don't know.
int length; // in seconds, set to -1 if you don't know
} mlAddPlaylist;

#define ML_IPC_PLAYLIST_ADD 0x180 // call to add a new playlist file to the Playlists treeview. pass an mlAddPlaylist *

typedef struct
{
size_t size; // size of this struct
const wchar_t *playlistName; // set to NULL (or empty string) to prompt the user for a name
int type; //ML_TYPE_ITEMRECORDLIST, etc
void *data; // object to load
int flags; // see PL_FLAG_* above
wchar_t filename[MAX_PATH]; // this will get populated if PL_FLAG_FILL_NAME is set
} mlMakePlaylistV2;

// old structure, here to make it easy to do a sizeof() check
typedef struct
{
size_t size; // size of this struct
const wchar_t *playlistName; // set to NULL (or empty string) to prompt the user for a name
int type; //ML_TYPE_ITEMRECORDLIST, etc
void *data; // object to load
int flags; // see PL_FLAG_* above
} mlMakePlaylist;

/* Call to add a new playlist to the Playlists treeview.
It will be automatically created based on the data you pass
type & data follow the same specifications as send-to, drag-and-drop, etc.
*/
#define ML_IPC_PLAYLIST_MAKE 0x181 // call to create a new playlist in the treeview based on passed information. pass an mlMakePlaylist *
#define ML_IPC_PLAYLIST_COUNT 0x182
#define ML_IPC_PLAYLIST_INFO 0x183 // pass in the struct below. returns "1" on success and "0" on failure

typedef struct
{
// you fill this in
size_t size; // size of this struct
size_t playlistNum; // number of the playlist you want to retrieve (0 index)
// ml_playlists fills these in
wchar_t playlistName[128];
wchar_t filename[MAX_PATH];
int numItems;
int length; // in seconds
} mlPlaylistInfo;

/** ------------------
**
** ------------------ */

#define ML_IPC_GETFILEINFO 0x0200 // pass it a &itemRecord with a valid filename (and all other fields NULL), and it will try to fill in the rest
#define ML_IPC_FREEFILEINFO 0x0201 // pass it a &itemRecord tha twas filled by getfileinfo, it will free the strings it allocated

#define ML_IPC_HANDLEDRAG 0x0300 // pass it a &mlDropItemStruct it will handle cursors etc (unless flags has the lowest bit set), and it will set result appropriately:
#define ML_IPC_HANDLEDROP 0x0301 // pass it a &mlDropItemStruct with data on drop:

#define ML_IPC_SENDTOWINAMP 0x302 // send with a mlSendToWinampStruct:
typedef struct {
int type; //ML_TYPE_ITEMRECORDLIST, etc
void *data; // object to play

int enqueue; // low bit set specifies enqueuing, and second bit NOT set specifies that
// the media library should use its default behavior as the user configured it (if
// enqueue is the default, the low bit will be flipped by the library)
} mlSendToWinampStruct;

typedef struct {
char *desc; // str
intptr_t context; // context passed by ML_MSG_ONSENDTOBUILD
intptr_t user32; // use some unique ptr in memory, you will get it back in ML_MSG_ONSENDTOSELECT...
} mlAddToSendToStruct;
#define ML_IPC_ADDTOSENDTO 0x0400

typedef struct {
wchar_t *desc; // str
intptr_t context; // context passed by ML_MSG_ONSENDTOBUILD
intptr_t user32; // use some unique ptr in memory, you will get it back in ML_MSG_ONSENDTOSELECT...
} mlAddToSendToStructW;
#define ML_IPC_ADDTOSENDTOW 0x0401 // pass mlAddToSendToStructW

// used to make a submenu in sendto
// pass mlAddToSendToStructW, set desc to 0 to start, set valid desc to end
// user32 is unused
#define ML_IPC_BRANCHSENDTO 0x0402

// follow same rules as ML_IPC_ADDTOSENDTOW, but adds to branch instead of main send-to menu
#define ML_IPC_ADDTOBRANCH 0x403 // pass mlAddToSendToStructW

#define ML_IPC_HOOKTITLE 0x0440 // this is like winamp's IPC_HOOK_TITLES... :) param1 is waHookTitleStruct
#define ML_IPC_HOOKEXTINFO 0x441 // called on IPC_GET_EXTENDED_FILE_INFO_HOOKABLE, param1 is extendedFileInfoStruct
#define ML_IPC_HOOKEXTINFOW 0x442 // called on IPC_GET_EXTENDED_FILE_INFO_HOOKABLEW, param1 is extendedFileInfoStructW
#define ML_IPC_HOOKTITLEW 0x0443 // this is like winamp's IPC_HOOK_TITLESW... :) param1 is waHookTitleStructW

#define ML_HANDLEDRAG_FLAG_NOCURSOR 1
#define ML_HANDLEDRAG_FLAG_NAME 2

typedef struct {
int type; //ML_TYPE_ITEMRECORDLIST, etc
void *data; // NULL if just querying

int result; // filled in by client: -1 if dont allow, 0 if dont know, 1 if allow.

POINT p; // cursor pos in screen coordinates
int flags;

char *name; // only valid if ML_HANDLEDRAG_FLAG_NAME

} mlDropItemStruct;

#define ML_IPC_SKIN_LISTVIEW 0x0500 // pass the hwnd of your listview. returns a handle to use with ML_IPC_UNSKIN_LISTVIEW
#define ML_IPC_UNSKIN_LISTVIEW 0x0501 // pass the handle you got from ML_IPC_SKIN_LISTVIEW
#define ML_IPC_LISTVIEW_UPDATE 0x0502 // pass the handle you got from ML_IPC_SKIN_LISTVIEW
#define ML_IPC_LISTVIEW_DISABLEHSCROLL 0x0503 // pass the handle you got from ML_IPC_SKIN_LISTVIEW
#define ML_IPC_LISTVIEW_DISABLEVSCROLL 0x050A // pass the handle you got from ML_IPC_SKIN_LISTVIEW
#define ML_IPC_LISTVIEW_SHOWSORT 0x0504 // use LV_SKIN_SHOWSORT
#define ML_IPC_LISTVIEW_SORT 0x0505 // use LV_SKIN_SORT

typedef struct
{
INT_PTR listView;
BOOL showSort;
} LV_SKIN_SHOWSORT;

typedef struct
{
INT_PTR listView;
int columnIndex;
BOOL ascending;
} LV_SKIN_SORT;

#define ML_IPC_SKIN_COMBOBOX 0x0508 // pass the hwnd of your combobox to skin, returns a ahndle to use with ML_IPC_UNSKIN_COMBOBOX
#define ML_IPC_UNSKIN_COMBOBOX 0x0509 // pass the handle from ML_IPC_SKIN_COMBOBOX

#define ML_IPC_SKIN_WADLG_GETFUNC 0x0600
// 1: return int (*WADlg_getColor)(int idx); // pass this an index, returns a RGB value (passing 0 or > 3 returns NULL)
// 2: return int (*WADlg_handleDialogMsgs)(HWND hwndDlg, UINT uMsg, WPARAM wParam, LPARAM lParam);
// 3: return void (*WADlg_DrawChildWindowBorders)(HWND hwndDlg, int *tab, int tabsize); // each entry in tab would be the id | DCW_*
// 32: return void (*childresize_init)(HWND hwndDlg, ChildWndResizeItem *list, int num);
// 33: return void (*childresize_resize)(HWND hwndDlg, ChildWndResizeItem *list, int num);
// 66: return (HFONT) font to use for dialog elements, if desired (0 otherwise)

// itemRecord type for use with ML_TYPE_ITEMRECORDLIST, as well as many other functions
typedef struct
{
char *filename;
char *title;
char *album;
char *artist;
char *comment;
char *genre;
int year;
int track;
int length;
char **extended_info;
// currently defined extended columns (while they are stored internally as integers
// they are passed using extended_info as strings):
// use getRecordExtendedItem and setRecordExtendedItem to get/set.
// for your own internal use, you can set other things, but the following values
// are what we use at the moment. Note that setting other things will be ignored
// by ML_IPC_DB*.
//
//"RATING" file rating. can be 1-5, or 0 or empty for undefined
//"PLAYCOUNT" number of file plays.
//"LASTPLAY" last time played, in standard time_t format
//"LASTUPD" last time updated in library, in standard time_t format
//"FILETIME" last known file time of file, in standard time_t format
//"FILESIZE" last known file size, in kilobytes.
//"BITRATE" file bitrate, in kbps
//"TYPE" - "0" for audio, "1" for video

} itemRecord;

typedef struct
{
itemRecord *Items;
int Size;
int Alloc;
} itemRecordList;

#include <time.h>

typedef struct
{
wchar_t *filename;
wchar_t *title;
wchar_t *album;
wchar_t *artist;
wchar_t *comment;
wchar_t *genre;
wchar_t *albumartist;
wchar_t *replaygain_album_gain; // these are strings rather than float's to differentiate between '0 gain' and 'not defined'
wchar_t *replaygain_track_gain; // these are strings rather than float's to differentiate between '0 gain' and 'not defined'
wchar_t *publisher;
wchar_t *composer;
int year;
int track;
int tracks;
int length;
int rating; // file rating. can be 1-5, or 0 for undefined
int playcount; // number of file plays.
__time64_t lastplay; // last time played, in standard time_t format
__time64_t lastupd; // last time updated in library, in standard time_t format
__time64_t filetime; // last known file time of file, in standard time_t format
int filesize; //last known file size, in kilobytes.
int bitrate; // file bitrate, in kbps
int type; // 0 for audio, 1 for video
int disc; // disc number
int discs; // number of discs
int bpm;
wchar_t **extended_info;
// currently defined extended columns (while they are stored internally as integers
// they are passed using extended_info as strings):
// use getRecordExtendedItem and setRecordExtendedItem to get/set.
// for your own internal use, you can set other things, but the following values
// are what we use at the moment. Note that setting other things will be ignored
// by ML_IPC_DB*.
//

} itemRecordW;

typedef struct
{
itemRecordW *Items;
int Size;
int Alloc;
} itemRecordListW;

//
// all return 1 on success, -1 on error. or 0 if not supported, maybe?

// pass these a mlQueryStruct
// results should be zeroed out before running a query, but if you wish you can run multiple queries and
// have it concatenate the results. tho it would be more efficient to just make one query that contains both,
// as running multiple queries might have duplicates etc.
// in general, though, if you need to treat "results" as if they are native, you should use
// copyRecordList to save a copy, then free the results using ML_IPC_DB_FREEQUERYRESULTS.
// if you need to keep an exact copy that you will only read (and will not modify), then you can
// use the one in the mlQueryStruct.

#define ML_IPC_DB_RUNQUERY 0x0700
#define ML_IPC_DB_RUNQUERY_SEARCH 0x0701 // "query" should be interpreted as keyword search instead of query string
#define ML_IPC_DB_RUNQUERY_FILENAME 0x0702 // searches for one exact filename match of "query"
#define ML_IPC_DB_RUNQUERY_INDEX 0x703 // retrieves item #(int)query

#define ML_IPC_DB_FREEQUERYRESULTS 0x0705 // frees memory allocated by ML_IPC_RUNQUERY (empties results)
typedef struct
{
char *query;
int max_results; // can be 0 for unlimited
itemRecordList results;
} mlQueryStruct;

/* Unicode versions of the above */

#define ML_IPC_DB_RUNQUERYW 0x1700
#define ML_IPC_DB_RUNQUERY_SEARCHW 0x1701 // "query" should be interpreted as keyword search instead of query string
#define ML_IPC_DB_RUNQUERY_FILENAMEW 0x1702 // searches for one exact filename match of "query"
#define ML_IPC_DB_RUNQUERY_INDEXW 0x1703 // retrieves item #(int)query
#define ML_IPC_DB_FREEQUERYRESULTSW 0x1705 // frees memory allocated by ML_IPC_RUNQUERYW (empties results)
typedef struct
{
wchar_t *query;
int max_results; // can be 0 for unlimited
itemRecordListW results;
} mlQueryStructW;

/* ----------------------------- */

// pass these an (itemRecord *) to add/update.
// note that any NULL fields in the itemRecord won't be updated,
// and year, track, or length of -1 prevents updating as well.
#define ML_IPC_DB_UPDATEITEM 0x0706 // returns -2 if item not found in db
#define ML_IPC_DB_ADDORUPDATEITEM 0x0707

#define ML_IPC_DB_REMOVEITEM 0x0708 // pass a char * to the filename to remove. returns -2 if file not found in db.

typedef struct
{
char* fileName; // file name to add
int meta_mode; // metadata get mode (0 - don't use metadata, 1 - use metadata; -1 - read from user settings (ini file)
int gues_mode; // metadata guessing mode (0 - smart, 1 - simple; 2 - no, -1 - read from user settings (ini file)
} LMDB_FILE_ADD_INFO;

#define ML_IPC_DB_UPDATEFILE 0x0710 // Update File in the Local Media Data Base (return -2 if file record not found)
#define ML_IPC_DB_ADDORUPDATEFILE 0x0711 // Adds or Updates File in the Local Media Data Base.

/* Unicode versions of the above */

// pass these an (itemRecordW *) to add/update.
// note that any NULL fields in the itemRecordW won't be updated,
// and year, track, or length of -1 prevents updating as well.
#define ML_IPC_DB_UPDATEITEMW 0x1706 // returns -2 if item not found in db
#define ML_IPC_DB_ADDORUPDATEITEMW 0x1707

typedef struct
{
wchar_t* fileName; // file name to add
int meta_mode; // metadata get mode (0 - don't use metadata, 1 - use metadata; -1 - read from user settings (ini file)
int gues_mode; // metadata guessing mode (0 - smart, 1 - simple; 2 - no, -1 - read from user settings (ini file)
} LMDB_FILE_ADD_INFOW;

#define ML_IPC_DB_UPDATEFILEW 0x1710 // Update File in the Local Media Data Base (return -2 if file record not found) NOTE that this call is broken on 5.33. Only use on 5.34+
#define ML_IPC_DB_ADDORUPDATEFILEW 0x1711 // Adds or Updates File in the Local Media Data Base.

/* ----------------------------- */

#define ML_IPC_DB_SYNCDB 0x0709 // sync db if dirty flags are set. good to do after a batch of updates.

// these return 0 if unsupported, -1 if failed, 1 if succeeded

// pass a winampMediaLibraryPlugin *. Will not call plugin's init() func.
// YOU MUST set winampMediaLibraryPlugin->hDllInstance to NULL, and version to MLHDR_VER
// 5.25+: You can set hDllInstance to valid value.
// This IPC will return -1 on failure, so a good check against old verions
// is to try with hDllInstance set, if it returns -1, try again with hDllInstance=0
#define ML_IPC_ADD_PLUGIN 0x0750
#define ML_IPC_REMOVE_PLUGIN 0x0751 // winampMediaLibraryPlugin * of plugin to remove. Will not call plugin's quit() func

#define ML_IPC_SEND_PLUGIN_MESSAGE 0x0752 // sends message to plugins (wParam = 0, lParam = pointer to the pluginMessage struct)
// pluginMessage struct
typedef struct {
int messageType;
INT_PTR param1;
INT_PTR param2;
INT_PTR param3;
} pluginMessage;

#define ML_IPC_ENSURE_VISIBLE 0x753 // ensures that the media library is visible
#define ML_IPC_IS_VISIBLE 0x754 // queries the current visibility status

#define ML_IPC_GET_PARENTAL_RATING 0x755

#define ML_IPC_TOGGLE_VISIBLE 0x756

// this gets sent to any child windows of the library windows, and then (if not
// handled) the library window itself

#define WM_ML_CHILDIPC WM_APP+0x800 // avoids conflicts with any windows controls
#define ML_CHILDIPC_DROPITEM 0x100 // lParam = 100, wParam = &mlDropItemStruct

// current item ratings
#define ML_IPC_SETRATING 0x0900 // lParam = 0 to 5, rates current track -- inserts it in the db if it's not in it yet
#define ML_IPC_GETRATING 0x0901 // return the current track's rating or 0 if not in db/no rating

// playlist entry rating
typedef struct {
int plentry;
int rating;
} pl_set_rating;

#define ML_IPC_PL_SETRATING 0x0902 // lParam = pointer to pl_set_rating struct
#define ML_IPC_PL_GETRATING 0x0903 // lParam = playlist entry, returns the rating or 0 if not in db/no rating

typedef struct {
HWND dialog_parent; // Use this window as a parent for the query editor dialog
const char *query; // The query to edit, or "" / null for new query
} ml_editquery;

#define ML_IPC_EDITQUERY 0x904 // lParam = pointer to ml_editquery struct, returns 0 if edition was canceled and 1 on success
// After returning, and if ok was clicked, the struct contains a pointer to the edited query. this pointer is static :
// - do *not* free it
// - if you need to keep it around, strdup it, as it may be changed later by other plugins calling ML_IPC_EDITQUERY.

typedef struct {
HWND dialog_parent; // Use this window as a parent for the view editor dialog
const char *query; // The query to edit, or "" / null for new views
const char *name; // Name of the view (ignored for new views)
int mode; // View mode (0=simple view, 1=artist/album view, -1=hide mode radio boxes)
} ml_editview;

#define ML_IPC_EDITVIEW 0x905 // lParam = pointer to ml_editview struct, returns 0 if edition was canceled and 1 on success
// After returning, and if ok was clicked, the struct contains the edited values. String pointers are static:
// - do *not* free them
// - if you need to keep them around, strdup them, as they may be changed later by other plugins calling ML_IPC_EDITQUERY.

#define ML_IPC_SET_FILE_RATING 0x0906 // lParam = 0 to 5, rates current track -- inserts it in the db if it's not in it yet
#define ML_IPC_GET_FILE_RATING 0x0907 // return the current track's rating or 0 if not in db/no rating

// playlist entry rating
typedef struct {
const char* fileName;
int newRating;
} file_set_rating;

#define ML_IPC_SMARTVIEW_COUNT 0x0908 // returns the number of smartviews. no parameter required
#define ML_IPC_SMARTVIEW_INFO 0x0909 // pass a mlSmartViewInfo*. returns 1 on success and 0 on failure
#define ML_IPC_SMARTVIEW_ADD 0x0910 // pass a mlSmartViewInfo* with filled in size, name, query, mode, iconImgIndex. treeitemid gets filled in. returns 1 on success and 0 on failure

typedef struct
{
// you fill these in
size_t size; // set to sizeof(mlSmartViewInfo)
size_t smartViewNum;
// ml_local fills these in
wchar_t smartViewName[128];
wchar_t smartViewQuery[512];
int mode;
int iconImgIndex;
int treeItemId;
} mlSmartViewInfo;

#define ML_IPC_SET_FILE_RATINGW 0x0911 // lParam = 0 to 5, rates current track -- inserts it in the db if it's not in it yet
#define ML_IPC_GET_FILE_RATINGW 0x0912 // return the current track's rating or 0 if not in db/no rating

// playlist entry rating
typedef struct {
const wchar_t *fileName;
int newRating;
} file_set_ratingW;
</source>

Language API

2008-09-25T13:04:58Z

Tarik: Protected "Language API" [edit=autoconfirmed:move=autoconfirmed]

Agave/Language/api_language.h

Image Loader Service

2008-09-25T13:02:48Z

Tarik: Protected "Image Loader Service" [edit=autoconfirmed:move=autoconfirmed]

Include file: api/service/svcs/svc_imgload.h

File Reader Service

2008-09-25T13:02:39Z

Tarik: Protected "File Reader Service" [edit=autoconfirmed:move=autoconfirmed]

Include file: api/service/svcs/svc_fileread.h

Creating Custom Cursors

2008-09-25T13:02:28Z

Tarik: Protected "Creating Custom Cursors" [edit=autoconfirmed:move=autoconfirmed]

XML Parser Object

2008-09-25T13:02:12Z

Tarik: Protected "XML Parser Object" [edit=autoconfirmed:move=autoconfirmed]

xml/obj_xml.h

WSZ Files

2008-09-25T13:02:06Z

Tarik: Protected "WSZ Files" [edit=autoconfirmed:move=autoconfirmed]

Text Feed Service

2008-09-25T13:02:00Z

Tarik: Protected "Text Feed Service" [edit=autoconfirmed:move=autoconfirmed]

Include file: api/service/svcs/svc_textfeed.h

Submitting Your Skin to Winamp.com

2008-09-25T13:01:53Z

Tarik: Protected "Submitting Your Skin to Winamp.com" [edit=autoconfirmed:move=autoconfirmed]

Skin API

2008-09-25T13:01:47Z

Tarik: Protected "Skin API" [edit=autoconfirmed:move=autoconfirmed]

api/skin/api_skin.h

Modern Skin API. Only present when gen_ff is loaded.

SDK Contents

2008-09-25T13:01:39Z

Tarik: Protected "SDK Contents" [edit=autoconfirmed:move=autoconfirmed]

Agave - collection of [[Wasabi API|Wasabi]] objects unique to Winamp 5

:Agave\AlbumArt - [[Album Art API]] interface definition files

:Agave\Component - [[System Component Interface|W5S system component]]interface definition files

:Agave\Config - [[Agave Config API|Winamp 5 configuration]]. Not be confused with the Winamp3 [[Wasabi Config API]]

:Agave\Language - [[Language API]]

:Agave\Metadata - [[Agave Metadata API]]

burner

coverdirectory - Cover Directory sample plugin. Demonstrates the [[Album Art API]], [[Service Factory|Service Factories]], and how to build a [[System Component Interface|System Component (W5S)]

dsp_test - [[Audio Effects plugin|DSP Plugin]] example

enc_flac - [[Audio Encoder Plugin]] example using the [http://flake-enc.sourceforge.net/ Flake] FLAC encoder. Although the project name is enc_flac, the plugin compiles as enc_flake.dll to allow it to co-exist with the [http://flac.sourceforge.net/api/index.html libFLAC] based encoder that ships with Winamp.

gen_classicart - Example [[General Purpose Plugin]] which demonstrates creating a Skinned window and the [[Album Art API]]

gen_ml - Collection of header files that comprise the [[Media Library API]] and the struct definition for creating a [[Media Library Plugin]]. Most of the content is contained in ml.h

gen_tray - Source code for the System Tray plugin which ships with Winamp.

in_chain - Example plugin showing how to use another input plugin within your own input plugin

in_raw - Example [[Input Plugin]]

in_tone - Example [[Input Plugin]]

irctell - Example [[System Component Interface|W5S]] plugin demonstrating [[System Callbacks API]] and the old Winamp3 [[Media Core API]] (only available in modern skins)

maki - Tools and include files for compiling maki scripts for use in the Modern Skinning engine. More information is available in the [[Skin Developer]] portion of this wiki.

ml_http - Example [[Media Library Plugin]] demonstrating using embedded IE and the Javascript [[Javascript External Interface|window.external]] interface.

ml_iso - Example [[Media Library Plugin]] demonstrating the send-to menu

ml_local - Header files comprising the Local Media Database API

ml_xmlex - Example [[Media Library Plugin]] demonstrating basic media libary UI concepts and the [[XML Parser object]]

mlExplorer - Standalone executable demonstrating how to use the [[Nullsoft Database Engine|Nullsoft Database Engine (NDE)]] in your own application to read Winamp's media library contents.

nde - [[Nullsoft Database Engine]] source code

nsv

nu

playlist

plLoadEx

ReplayGainAnalysis

Wasabi

Winamp

xml

xspf

Index.php/Winamp Developer Connect Wiki Terms and Conditions

2008-09-25T13:01:28Z

Tarik: Protected "Index.php/Winamp Developer Connect Wiki Terms and Conditions" [edit=sysop:move=sysop]

==Winamp Developer Connect Wiki Terms and Conditions==

Welcome! The following terms govern your access, use and participate in Winamp’s Developer Connect Wiki (“Wiki Service”).

BY REGISTERING OR BY USING THE WIKI SERVICE, YOU SIGNIFY ELECTRONICALLY YOUR AGREEMENT TO THE FOLLOWING TERMS. If you do not agree, you may not use the Wiki Service.

==About the Developer Connect Wiki==

The Wiki Service is a centralized resource that offers a consolidation of Winamp documentation, code samples, reference materials, and sample articles and gives the development community a place to share information. We offer the Wiki Service to help facilitate the development of Winamp skins, plugins, and visualization presets.

==About These Terms==

The Wiki Service is provided by Nullsoft, Inc. and its affiliates (collectively, “we” or “us”). In order to use the Wiki Service, you must abide by Nullsoft Terms of Use for Winamp.com (http://www.winamp.com/legal/terms), the supplemental Wiki terms below, the Wiki Policy and Guidelines located at (http://qawinamptools.stream.aol.com/wiki/index.php/Policies_%26_Guidelines) and such other policies that we may post from time to time on the Wiki Service. These terms collectively make up your agreement with us regarding your access and use the Wiki Service (the “Terms”). We may change these Terms at any time. Your ongoing use of the Wiki Service after we post or notify you about changes to our terms signifies your agreement electronically to the updated terms.

==Your requirements==

In order to use the Wiki Service, you must register with us and provide complete, accurate and current information about yourself. You must keep this information up to date at all times. You must comply at all times with applicable laws and these Terms.

==Use of Information==

The Winamp Privacy Policy located at http://www.winamp.com/legal/privacy explains the practices that apply to your information when you use the Wiki Service. Your ongoing use of the Wiki Service signifies your consent to the information practices disclosed in our Privacy Policy.

==Use of Wiki Service==

You may not submit or transmit through the Wiki Service any material, or otherwise engage in any conduct that:
#violates or infringes the rights of others including, without limitation, patent, trademark, trade secret, copyright, publicity or other proprietary rights,
#is unlawful, threatening, abusive, harassing, defamatory, libelous, deceptive, fraudulent, invasive of another's privacy, tortious, or contains explicit or graphic descriptions, or accounts of, sexual acts,
#victimizes, harasses, degrades, or intimidates an individual or group of individuals on the basis of religion, gender, sexual orientation, race, ethnicity, age, or disability,
#impersonates any person, business or entity,
#contains viruses or any other malicious computer code,
#encourages conduct that would constitute a criminal offense, or that gives rise to civil liability,
#transmits, directly or indirectly, any unsolicited bulk communications (including e-mails, “spam” and instant messages),
#violates these Terms, including without limitation, the Nullsoft Terms of Use for Winamp.com, or
#interferes with the use of the Wiki Service or any other area on Winamp.com by others.

==Ownership==

The content on Wiki Service including, without limitation, images, graphics, audio, music, videos, texts, software, feedback, data, messages, answers, questions, comments, suggestions, ideas or any other materials (“Content”) are owned or licensed by us and protected under copyright and other intellectual property right laws. All trade names, trademarks and service marks appearing on the Content are protected by Nullsoft, Inc., its parent and affiliates or respective third party owners. Any rights not expressly granted herein are reserved. All Content is for your application development purposes and for your personal use only and may not be modified, reproduced, transmitted, published, exploited, sold, licensed or distributed to any third parties or in combination with any applications if the Content would constitute the primary value of the product being distributed.

==Submissions==

The Wiki Service allows users to upload, download, edit, host, share and/or publish Content (“User Content”). We may, in our sole discretion, incorporate such User Content into any of our products or services.

You are solely responsible for any submission of User Content. You may only submit User Content that you own or that you have acquired such consents, permissions or licenses needed to submit such Content. If your User Content contains content of a third party or open source material, you shall clearly notify us of such third-party material together with any license terms that deviate from those specified in these Terms, as well as be responsible for acquiring consent for such use the User Content. Any such third party content or open source material shall be subject to your obligation to indemnify us. Upon submission of any User Content to the Wiki Service, you will grant us and our parent a worldwide, perpetual, irrevocable, royalty-free, non-exclusive, assignable and sublicensable license to use, reproduce, modify, create derivative works, publicly perform and display such User Content in connection with any of our products or services, entirely without obligation, compensation or restriction of any kind.

==No Duty to Monitor==

You agree that we are not liable for Content (including User Content) that is provided by others. We have no duty to pre-screen Content, but we have the right to refuse to post or to edit submitted Content. We reserve the right to remove Content for any reason, but we are not responsible for any failure or delay in removing such material.

==Procedure for Making Claims of Copyright Infringement.==

We respect the intellectual property of others. If you believe that your work has been copied and is accessible on the Wiki Service in a way that constitutes copyright infringement, please click here <http://about.aol.com/aolnetwork/copyright_infringement> for instructions on how to contact us to report possible copyright infringement.

==No Warranties==

We provide the Wiki Service "as is", "with all faults" and "as available." You use the Content and Wiki Service at your own risk. We and our suppliers and distributors make no express warranties or guarantees about the Wiki Service. TO THE EXTENT PERMITTED BY LAW, WE AND OUR SUPPLIERS DISCLAIM IMPLIED WARRANTIES THAT THE WIKI SERVICE ARE MERCHANTABLE, OF SATISFACTORY QUALITY, ACCURATE, TIMELY, FIT FOR A PARTICULAR PURPOSE OR NEED, OR NON-INFRINGING. WE DO NOT GUARANTEE THAT THE WIKI SERVICE WILL MEET YOUR REQUIREMENTS, IS ERROR-FREE, RELIABLE, WITHOUT INTERRUPTION OR AVAILABLE AT ALL TIMES. WE DO NOT GUARANTEE THAT THE RESULTS THAT MAY BE OBTAINED FROM THE WIKI SERVICE OR THAT YOU WILL BE ABLE TO ACCESS THE WIKI SERVICE AT ALL TIMES. You may have additional consumer rights under your local laws that this contract cannot change.

==Limitation of Liability==

YOUR SOLE AND EXCLUSIVE REMEDY FOR ANY DISPUTE WITH US IS TO DISCONTINUE YOUR USE OF THE WIKI SERVICE. WE, OUR PARENT, AND OUR SUPPLIERS SHALL NOT BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES ARISING FROM YOUR USE OF, INABILITY TO USE, OR RELIANCE UPON AOL.COM. THESE EXCLUSIONS APPLY TO ANY CLAIMS FOR LOST PROFITS, LOST DATA, LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF WE KNEW OR SHOULD HAVE KNOWN OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR THE LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, IN SUCH STATES OR JURISDICTIONS, OUR LIABILITY, AND THE LIABILITY OF OUR PARENT AND SUPPLIERS, SHALL BE LIMITED TO THE EXTENT PERMITTED BY LAW.

==Indemnification==

Upon a request by us, you agree to defend, indemnify, and hold harmless us and our parent and other affiliated companies, and our respective employees, contractors, officers, directors, and agents from all liabilities, claims, and expenses, including attorney's fees that arise from your use or misuse of the Wiki Service. We reserve the right, at our own expense, to assume the exclusive defense and control of any matter otherwise subject to indemnification by you, in which event you will cooperate with us in asserting any available defenses.

==International Use==

We make no representation that Content on the Wiki Service is appropriate or available for use in locations outside the United States, and accessing it from territories where the Content is illegal is prohibited. If you choose to access the Wiki Service from a location outside the U.S., you do so on your own initiative and you are responsible for compliance with local laws.

==Software Restrictions==

Any software offered through the Wiki Service is a "commercial item," as that term is defined in 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation," as such terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 27.405(b)(2) (June 1998) and 48 C.F.R. 227.7202, all U.S. Government end users acquire the software with only those rights as set forth herein. You agree to fully comply with all import and export laws, regulations, rules and orders of the United States, or any foreign government agency or authority, and that you will not directly or indirectly export, re-export, transfer and/or release the software, related technology, or any product thereof, for any proscribed end-use, or to any proscribed country, entity or person (wherever located), without proper authorization from the U.S. and/or foreign government.

==Choice of Law==

You agree that the laws of the Commonwealth of Virginia govern this contract and any claim or dispute that you may have against us, without regard to Virginia’s conflict of laws rules, and that the United Nations Convention on Contracts for the International Sale of Goods shall have no applicability. You further agree that any disputes or claims that you may have against us will be resolved by a court located in the Commonwealth of Virginia and you agree and submit to the exercise of personal jurisdiction of such courts for the purpose of litigating any such claim or action. PLEASE NOTE THAT BY AGREEING TO THESE TERMS OF USE, YOU ARE: (1) WAIVING CLAIMS THAT YOU MIGHT OTHERWISE HAVE AGAINST US BASED ON THE LAWS OF OTHER JURISDICTIONS, INCLUDING YOUR OWN; (2) IRREVOCABLY CONSENTING TO THE EXCLUSIVE JURISDICTION OF, AND VENUE IN, STATE OR FEDERAL COURTS IN THE COMMONWEALTH OF VIRGINIA OVER ANY DISPUTES OR CLAIMS YOU HAVE WITH US; AND (3) SUBMITTING YOURSELF TO THE PERSONAL JURISDICTION OF COURTS LOCATED IN THE COMMONWEALTH OF VIRGINIA FOR THE PURPOSE OF RESOLVING ANY SUCH DISPUTES OR CLAIMS.

==Termination==

Your right to use the Wiki Service automatically terminates if you violate these Terms or any rules or guidelines posted in connection with AOL.COM. We also reserve the right, in our sole discretion, to terminate your access to all or part of the Wiki Service, for any reason, with or without notice.

==Electronic Notices==

YOU AGREE TO TRANSACT WITH US ELECTRONICALLY. WE MAY PROVIDE NOTICES TO YOU ELECTRONICALLY (1) VIA E-MAIL IF YOU HAVE PROVIDED US WITH A VALID EMAIL ADDRESS OR (2) BY POSTING THE NOTICE ON A WEBSITE DESIGNATED BY US FOR THIS PURPOSE. The delivery of any Notice is effective when sent or posted by us, regardless of whether you read the Notice or actually receive delivery. You can withdraw your consent to receive Notices electronically by discontinuing your use of the Wiki Service.

==General Terms==

(a) This agreement constitutes the entire agreement between you and us concerning the subject matter of these Terms, which may only be modified by us. (b) This Agreement shall not be governed by the United Nations Convention on Contracts for the International Sale of Goods. (c) If any part of these Terms is held invalid or unenforceable, that part shall be construed to reflect the parties' original intent as nearly as practicable, and the remaining portions remain in full force and effect, or we may at its option instead terminate this Agreement. (d) English is the controlling language of these Terms. If you have received a translation into another language, it has been provided for your convenience only. (e) A waiver by either party of any term or condition of this Agreement or any breach thereof, in any one instance, shall not waive such term or condition or any subsequent breach thereof. (f) You may not assign or otherwise transfer by operation of law or otherwise this Agreement or any rights or obligations herein. We may assign these Terms to any entity, including to any of our affiliates or parent at our sole discretion. (g) These Terms shall be binding upon and shall inure to the benefit of the parties, their successors and permitted assigns.

Plugin Terminology

2008-09-25T13:00:16Z

Tarik: Protected "Plugin Terminology" [edit=autoconfirmed:move=autoconfirmed]

== winamp plugin filename conventions ==
Most plugin types are identified by Winamp by the filename
* in_*.dll - input plugins
* out_*.dll - output plugins
* gen_*.dll - general purpose plugins
* vis_*.dll - visualizer plugins
* dsp_*.dll - audio effects plugins
* ml_*.dll - media library plugins (loaded by gen_ml.dll)
* pmp_*.dll - portable media player plugins (loaded by ml_pmp.dll... a plugin type loaded by a plugin of a plugin. hah!)
* nsvdec_*.dll - NSV decoder plugins
* enc_*.dll - audio encoder plugins
* W5S (Winamp 5 System) plugins located in c:\program files\winamp\system do not have to follow any special filename convention except for the .w5s file extension
* WAC (Winamp Component) plugins located in c:\program files\winamp\plugins\freeform\wacs do not have to follow any special filename conventions, either, except for the .wac file extension. WAC files are loaded by gen_ff.dll

== code naming conventions ==
* IPC: Inter-Plugin Communications. The constants which define the old SendMessage API are prefixed with IPC_
* Wasabi: Winamp Service Architecture Binary Interface. A system to allow sharing of C++ objects between different plugins and components. Think of it as a very lightweight version of COM.
* Agave: project codename for Winamp 5.12 (when the Wasabi service manager was merged into Winamp 5. It may or may not have involved a lot of tequila). The name "Agave" is used in the SDK to refer to Wasabi components that are unique to Winamp's media platform. For example: the Wasabi Language API could be used in other (non-Winamp) Wasabi applications, but the Agave Playlist Manager makes very little sense outside of a media application.

Wasabi interfaces are all built using the Dispatchable base class. A naming convention has been established to help developers understand the intent of the interface.
* ifc: interface. Wasabi interfaces not associated with the service manager are prefixed with this, e.g. ifc_window
* api: Wasabi interfaces which expose a singleton object meant to be used as a global API. e.g. api_application
* svc: service. Wasabi interfaces which define a service are prefixed with this, e.g. svc_playlisthandler
* obj: object. Wasabi interfaces which define an object created by the service manager are prefixed with this. e.g. obj_xml for an instance of an XML parser.