Quick Start MAME HLSL Guide

If you are missing the HLSL folder in your Mame, you can get it from here.
http://www.mediafire.com/?ns2gn8pf2wf8ngy
Extract the .zip file to your Mame folder and it will automatically create the HLSL folder for you.

*Sometimes with HLSL if you try to [ALT][TAB] to desktop, Mame will crash when you go back to it. If you need to go to your desktop then you probably want to use save states for the game you are playing. Does not happen with all games though.
**You may notice a error box come up everytime you exit from a game. That is an on going bug between HLSL and Mame that has not been fixed yet. On further inspection it might actually be a conflict/bug with the M+GUI. Just ignore it as does not crash Mame and you can load another game up straight away.

I have not tested whether multiple individual HLSL settings files are working yet so I will say easiest way for people to test at the moment is to use a single HLSL.ini file for all games which I will show you how to setup below:

You must have two files in your artwork folder (aperture.png & white.png) these are the default ones that are included with the HLSL filter:
http://www.mediafire.com/?5u2t6zm25op8of2

***DO NOT MAKE CHANGES TO HLSL SETTINGS INSIDE MAME, USE NOTEPAD***
HLSL is still tricky to work with, but here is some tips;
1. In Mame folder mame.ini make sure these are setup:
#
# DIRECT3D POST-PROCESSING OPTIONS
#
hlsl_enable 1 (Turn HLSL on with 1 or Turn HLSL off with 0)
hlslpath hlsl (Folder inside MAME where HLSL files are kept)
hlsl_ini_read 1 (Tells MAME to read HLSL ini file for settings otherwise read from inside mame.ini only)
hlsl_ini_write 0 (Tells MAME to write any HLSL changes made in mame.ini to hlsl.ini, in previous versions 'overwriting' settings was problematic so was recommended not to use this option and make adjustments to hlsl.ini manually. I have not tested whether it is fixed yet or not.)
hlslini hlsl.ini (Name of hlsl settings file, I just use hlsl.ini at moment)
hlsl_preset -1 (Currently an undocumented setting)
shadow_mask_texture aperture.png (Name of shadow_mask 'overlay' file)

You must have hlsl.ini file in your hlsl folder, you can download my example for "Metal Slug 1" here but you need to change settings to suit as in step2 below:
http://www.mediafire.com/?c41stv15oetuft1

***DO NOT COPY AND PASTE THIS AS MY EXTRA COMMENTS WILL BREAK FILE***
2. In HLSL folder hlsl.ini is where you do all your settings manually in notepad:
hlsl_enable 1 (Turn HLSL on with 1 or Turn HLSL off with 0, best to configure this setting in mame.ini)
hlsl_prescale_x 2 (This setting can give you a 'sharper' image depending on what resolution you play games at. For example, if you are playing a 320x240 game at 1280x960 then you are using a 4x magnification. Here you put 4 for a 4x pre-multiplication in horizontal pixels)
hlsl_prescale_y 2 (This setting can give you a 'sharper' image depending on what resolution you play games at. For example, if you are playing a 320x240 game at 960x720 then you are using a 3x magnification. Here you put 3 for a 3x pre-multiplication in vertical pixels)
hlsl_preset -1 (Currently an undocumented setting)
hlsl_snap_width 5120 (This setting sets the width for huge resolution 'rendered snapshots' that can be created by default hotkey [LEFT ALT] & [F12]. Usually best used at a multiple of your playing output resolution. For example 1280 wide x4 = 4160)
hlsl_snap_height 3840 (This setting sets the height for huge resolution 'rendered snapshots' that can be created by default hotkey [LEFT ALT] & [F12]. Usually best used at a multiple of your playing output resolution. For example 960 high x4 = 3840)
shadow_mask_alpha 0.050000 (visibility of shadow mask, when using big game display output use small numbers here. If you use the default aperture.png you need to use an even smaller number here to remove the moiré effect)
shadow_mask_texture aperture.png (Name of shadow_mask 'overlay' file)
shadow_mask_x_count 320 (Here is where we tell the HLSL file how many times to tile the 'aperture.png' to fill the resolution. Using the default 'aperture.png' you will notice moiré effects. To remove this problem input the original games width resolution here)
shadow_mask_y_count 240 (Here is where we tell the HLSL file how many times to tile the 'aperture.png' to fill the resolution. Using the default 'aperture.png' you will notice moiré effects. To remove this problem input the original games height resolution here)
shadow_mask_usize 0.187500 (This tells the HLSL filter how to wrap the 'aperture.png' horizontally so that when tiling everything will line up correctly. Doesn't work correctly with the default 'aperture.png')
shadow_mask_vsize 0.093750 (This tells the HLSL filter how to wrap the 'aperture.png' vertically so that when tiling everything will line up correctly. Doesn't work correctly with the default 'aperture.png')
curvature 0.150000 (Suppose to curve the 'aperture.png' with the curve of the screen if you also use pincushin? Is working with recent HLSL versions)
pincushion 0.150000 (This can give you that cool fishbowl effect. Is working with recent HLSL versions)
scanline_alpha 0.100000 (visibility of scanlines, when using big game display output use small numbers here)
scanline_size 1.000000 (just set to one if you want them? Unrevised setting)
scanline_height 0.750000 (this is like 75% scanline which is personal preference? Undocumented setting)
scanline_bright_scale 1.000000 (just set to one if you want them? Unrevised setting)
scanline_bright_offset 0.500000 (this is like 50% so they don't show up too strong? Unrevised setting)
scanline_jitter 0.000000 (I don't use, makes scanlines shimmer up and down. Is working with recent HLSL versions. Unrevised setting)
defocus 0.000000,0.000000 (I don't use defocus as is only used to add blurriness to your game image, yuck!)
converge_x 0.000000,0.000000,0.000000 (I don't use, suppose to offset pixel position by colours)
converge_y 0.000000,0.000000,0.000000 (I don't use, suppose to offset pixel position by colours)
radial_converge_x 0.000000,0.000000,0.000000 (I don't use, suppose to offset pixel position by colours)
radial_converge_y 0.000000,0.000000,0.000000 (I don't use, suppose to offset pixel position by colours)
red_ratio 1.000000,0.000000,0.000000 (leave alone, red ratio 100%)
grn_ratio 0.000000,1.000000,0.000000 (leave alone, green ratio 100%)
blu_ratio 0.000000,0.000000,1.000000 (leave alone, blue ratio 100%)
saturation 1.150000 (this is saturation, how strong colours look/bleed, don't set too high)
offset 0.000000,0.000000,0.000000 (I don't use, suppose to offset strength of red,blue,green)
scale 0.950000,0.950000,0.950000 (I think of this like brightness control, where 1.0 = 100%)
power 1.100000,1.100000,1.100000 (I think of this like contrast control, where 1.0 = 100%)
floor 0.000000,0.000000,0.000000 (I think of this like gamma control, I don't like gamma creates washed out colours)
phosphor_life 0.200000,0.200000,0.200000 (can create a ghosting effect on fast moving sprites, up to you if you like or not? When using big game display output use small numbers here)

*What I mean by big game display output is like when you take original game resolution of 320x240 and output that at 1280x960 or even bigger for example. Some of the above settings are very sensitive to this and so we have to use smaller numbers, for example 0.200000 instead of 1.000000.
**Game output resolution is setup inside Mame, so you would have already done that before and know what your output resolution is.
**To keep aspect ratio with big output resolutions you may need to use Mame's bezel border artwork feature to do this. It is actually a very powerful feature that is fully customizable, for instance you could set it up so you just have plain black borders with no artwork if you want. Can even create some nice transparent edged borders instead of hard edged and you can also place the game display box in any position of screen. Also is really good because you can create any magnification or aspect ratio for game output display as you like as is unlimited possibilities. When making my own border artwork I find it is best to work in 1:1 ratio, for example if my display output is 1280x1024 then I make my border artwork at 1280x1024 and then put a 304x224 game 4x aspect ratio 1216x896 into a box inside the border of 1280x1024. Looks really good and crystal clear.    

4. Having everything setup like above means that there is only one hlsl.ini file that is used all the time for all games.
I find that best way to setup hlsl.ini file is per original game resolutions. For example one hlsl.ini file for all 320x240 games, one hlsl.ini file for all 288x224 games, etc, etc....
If some games of certain driver all have same resolution maybe you could make a hlsl.ini just for NeoGeo games for example???
This means you have to create your own backup of hlsl.ini with names that you can remember and then copy and paste hlsl.ini when you want to play a game. I know sounds sucky but that is only way it works at moment because the current HLSL implementation does not overwrite settings properly from inside Mame which is why we have to modify hlsl.ini manually with notepad. Maybe in future will work properly and no longer a problem?

5. You can have Mame running and quit out of game. Then make changes in hlsl.ini with notepad and save. Then switch back to Mame and start game up. Then quit out of game and make more changes to hlsl.ini with notepad and save. Then switch back to Mame and start game up. Repeat, repeat, repeat... (You don't need to exit Mame and then restart Mame, each time, see).

Once you have seen HLSL setup properly you can never go back!
Here is an example of MSlug1 320x224 (original game res including internal aspect ratio black borders) HLSL to 1280x896 then displayed inside custom made bezel artworked canvas of 1280x1024 (native res of my monitor)
http://i49.servimg.com/u/f49/16/79/18/18/best_m10.jpg