MacX_romcnv by b8a
-----------------------------------------------------------------------------------------
Updated 2007-01-17

Overview
-----------------------------------------------------------------------------------------
This is an application for Mac OS X that allows you to convert MAME compatible NEOGEO and CPS2 ROMs for use with NJ's MVSPSP and CPS2PSP arcade emulators for the PSP.

It should go without saying, but this application is only for use with ROM images for games that you legally and legitimately own.  Further, you use this application at your own risk and it's developers and distributors can not and will not be responsible for any possible damages or undesired effects arising from it's usage.

At it's core, this application is merely a port of NJ's original converters made for Windows.  The original source code compiles readily with very few changes, so I decided to take the project one step further and created a GUI front end as well.  Accordingly, I also made a few additional changes to the basic converters beyond what was required to get them working on OS X so that they can better communicate with the GUI.  My original intention was to make the GUI as compatible with as many OS X versions as possible, but many of the features that I consider basic require a minimum of 10.3.  It should work on higher versions as well, but I have only tested it on a PowerPC running 10.3.9.

romcnv_mvs, the MVS ROM converter backend, was ported from the most recent version (6) and should convert ROMs for compatibility with MVSPSP versions 1.50 and later.

romcnv_cps2, the CPS2 ROM converter backend, was ported from the most recent version (9.2).  It should generate raw cache files that are compatible with CPS2PSP 1.66 and compressed cache files that are compatible with 1.30 and later.

The command line tool backends are fairly low level C and, to my knowledge, should work on all versions of OS X.  The one caveat to this that I can think of is that you must have zip installed if you want to use the "Remove unused files from original ROM" option.  But since zip is installed by default, I don't imagine anyone will have a problem with this.

I do not know if either the front end or the CLI tools will run on Intels.  I do not know what steps would need to be taken to produce an Intel compatible binary, or if it's even possible to produce one on my machine.  In any case, I have no way to test for Intel compatibility on my end.


Usage
-----------------------------------------------------------------------------------------
The usage is pretty basic.  You can convert ROMs either via the GUI or you can use the tools directly via the command line (in order to access the raw CLI tools you'll have to navigate to MacOS->converters inside the application package).  If you give it a go and find yourself lost or confused, see below for an exhaustive explanation.

-Using The GUI
---------------
The GUI front end simplifies the conversion process by giving you various options for specifying the conversion paramaters.  A pane is provided for both MVS and CPS2 paramaters.  If you fill out both MVS and CPS2 panes, the GUI will convert all of the specified files for both converters all at once.

At the very top of each pane is a pop-up menu that allows you to select the emulator version that you want to convert files for.  It should be disabled and unselectable by default.  I implemented it for two reasons.  1) This mechanism makes it so that you can simply update the backend tools should NJ ever update the converters again (meaning that you wouldn't have to re-download this whole package, only the portions that had actually been updated), and 2) I was working on the GUI in my free time over the past few months, during that same time period NJ updated the converters countless times, and this allowed to me to keep multiple converter versionson my machine at the same time.  In other words, since it looks like NJ may finally be done updating his emulators for good, you'll probably never need to pay any attention to this field.

Next is a field for specifying the output path for the converted files.  Either:
a) Type a valid folder path into the text field
b) Use the "Choose Folder" button and select an appropriate folder
Or,
c) Drag a folder image directly from the finder and drop it on the text field

After that, you're provided with the option to convert either a single ZIP file or every ZIP file contained in a single folder.  The text field below that works exactly the same as the previous field (described above), except that if you choose a single file, then the path must be to a valid ZIP file that exists on your computer.

The GUI will not convert files for either MVS or CPS2 if:
1) It can not find at least one valid corresponding tool
2) You do not provide a valid output (save) folder
3) You do not provide valid input file(s)

You will also be given the option to remove unused files from the original ROM.  CAUTION: This option will permanently modifiy the original zipped ROM file, so you should only use it if you don't plan on using the original ROM with other emulators as well.

For CPS2 ROM conversion, you will also be given the option to create compressed cache files.  While this option does create more compact cache files (allowing you to store more files on your Memory Sitck), most games run less than satisfactory with compressed cache files, and the compression process also takes significantly longer to complete then cache file generation process.  In other words, you probably don't want to use this option.  However, it is available if you'd like.

A somewhat easier way to use the GUI is to simply drag-and-drop files on the application's icon.  This methoud checks all files (and all files embedded in any folders) dropped on the icon for any ZIP files and processes all of them through the converters you specify.  The drawback to this methoud is that it deep checks for all ZIP files in any dropped folders and processes all of them.  Theoretically, you could drop your User folder and this would check every single ZIP in your user domain (it will not process files that you are denied access to).  On top of that, if you tell it to check for both MVS and CPS2 files, then it will repeat the process for both converters.  If it finds 1000 ZIP files, it will process all of them, even if there are only a few __valid__ ROM files, and if you've told it to check both MVS and CPS2, then that means that it would run all 1000 checks twice for a total of 2000 checks.  Accordingly, the best way to use this option is to select all of the files you want to process in the finder and drag-and-drop them, or to only drag and drop folders that __only__ contain MVS/CPS2 ROMs.  These are the usage scenarios that I designed the feature for and have never extensively tested the deep checking feature beyond three or four layers of folders.

-Using The Command Line Tools
-----------------------------
Due to the way NJ originally designed the tools and my explicit purpose of porting (as opposed to recreating) those tools, I've built these tools so that they require full path (as opposed to relative path) parameters.  If you are unfamiliar with the difference between full paths and relative paths, then I recomend that for any parameter that requires a full path, you physically drag the corresponding item from the finder into the terminal window.  This will automatically insert the item's full path for you.

You can use the tools by first providing the full path to the corresponding tool at the command line prompt, then any options you want to use, followed by the full path to a folder to save the converted files to, and ending with the full path to the item to convert.  The only mandatory parameters are the output path and input file, and they must be specified in that order.

The only option available to both MVS and CPS2 converters is -d.  Specifying this parameter removes any files that have been converted from the original zipped ROM after the conversion has been successfully completed.  No warning will be given before it attempts to remove the files.  CAUTION: This option will permanently modifiy the original zipped ROM file, so you should only use it if you don't plan on using the original ROM with other emulators as well.

CPS2 also offers the following command line options:

	-all	When you use this option, the final parameter that you specify should be a folder (as opposed to a single file) containing any CPS2 ROMs that you want to convert.  This option uses rominfo.cps2 to check which of the files recorded there are actually available in the specified input path.  Any files that it successfully finds will be converted using any other options you specify when running the tool.
	
	-z		This option causes the tool to create compressed cache files.

Source Code
-----------------------------------------------------------------------------------------
While I have provided the source that I used to create this application, the code for the GUI front end is only being provided as an example of how to code many common Carbon GUI tasks.  It is meant as a reference only and I ask that anyone who wants to modify the code and distribute resulting products contact me first.  I don't really imagine that there is anything anyone would want to tweak about this application, but I would like to know if anyone optimizes it or otherwise further improves it.  In the case of legitimate improvements, I will happily merge the changes with the official build and give full credit to whoever submitted them.

The provided code for the CLI backend tools are considerably more complicated (and confusing) then what is required to simply achieve a successful build from NJ's raw source.  If you're interested in building any of NJ's past or future converter versions for use with the supplied GUI front end, then you should compare NJ's source with the provided code to see what changes I made.  But since I doubt that many people will be interested in anything other than any possible newest converter versions, I will only explain the steps that it takes to achieve a build that simply works as a stand alone command line tool on OS X.  I assume that the changes should also work to achieve a successful build on other *NIX systems as well.

Thankfully there isn't much windows specific code to worry about, but NJ does use several windows specific API calls.  If you use the header file "macport.h" from my source and add it to the top of the romcnv.h files for both the MVS and CPS2 romcnv projects, then that should take care of most of the windows related issues (however, keep in mind that I moved some of the variable type declarations to macport.h, so you're going to need to remove them from each of the romcnv.h files), but there are still several others that you need to deal with:

-Remove windows specific headers (windows.h, conio.h, direct.h, malloc.h, and zip32j.h)

-Remove the file_dialog function and the call to it.  This requires that you handle the eventuality that the user doesn't supply an input file in some other way.  I dealt with this in my release version by requiring that the input file be specified as a command line option, but you could just as easily display a prompt to input the file.

-Change any code that checks paths for windows path separators (\) and change them to POSIX path seperators (/).  The windows specific instances are pretty easy to find since the \ character has to be escaped, and therefore should always appear as "\\".

-If you are porting a converter that automatically handles compression of the converted cache files, you will need to change all lines that handle that.  The way NJ handles the compression is to
a) write all of the raw cache files to a temporary directory,
b) write the names of all of those files to a text file, and then,
c) feed that file to a Windows specific function that reads the names of those files from the text and zip compresses them.
Thanks to the fact that Macs ship with zip as a standard install, you can use these same steps without worrying about the zip DLL that NJ uses for the Windows version, you just need to make sure that you tweek all of the code that handles this process appropriately.

-Finally, there are a few other conflicts that I ran across that kept the converters from initially building.  First, I ran into a naming conflict with "zopen" so I just changed all occurances in all of the original source to "z_open".  Secondly, for some reason, romcnv.h is included twice in neocrypt.c, which was preventing a successful build.  I merely commented out the second include.

-There are also a few endian related issues to deal with.  I _assume_ that you don't need to worry about these if you are porting for/on an Intel machine:

--romcnv_mvs-- There are a couple of IFDEF's inside neocrypt.c.  Either you can set this variable in a compiler rule, or you can simply remove the IFDEF and the entire lower conditions.
Also, when converting games that have the SMA chip (kof99, garou, garouo, mslug3, and kof2002), you need to swap the bytes in memory_region_cpu1 before and after it's contents are decrypted.

--romcnv_cps2-- At some point after romcnv_cps2 version 7, NJ changed the tool so that it would create single-file uncompressed cache files.  In the function create_raw_cache, there is a loop that sets up the block array.  You'll need to swap the value of offset when it is set to block[i].

Following these steps should lead you to a no-frills command line tool build that will work on the Mac.  It's really not that hard and since every Mac ships with the tools that you need to get it done, there's really no reason to wait for someone else to port the tools if you ever find a version that you want to run on a Mac, but that isn't already available.