The picture below shows the last state of the solution we were using as an example for the series:
Let me remind you that the raw files named "bkgClouds" were bound to different source files: one sized 640x400 texels and another sized 320x200 texels.
Since the APE does not come bundled with any import/write units other than the pass-through ones, y clicking in one of the raw files we'll get the following view on the raw file tab:
Thus, as you can see, the pass-through importer is assigned by default to all the raw files in the solution. This default importer has no properties we can modify since all it does is to copy the source file associated to each raw file to the destination folder without any kind of processing/formatting.
However, there is one property that I'd like to highlight here that I didn't mention on my previous posts, and that is the checkbox named "Build Asset ?". If you have been following the series then you'll likely remember that for solutions and projects you could indicate the actions to execute for building and copying/moving, right? Well, this checkbox allows us to override those settings for a specific raw file, so if we unmark it, no build/copy actions will be applied to that raw file.
In fact, if you carefully look at the first screenshot above corresponding to the solution tree, you will notice a checkbox beside some of the nodes. By checking/unchecking that control not only we can include/exclude a raw file for build/copy actions but also the nodes of an entire folder or container. And yes, when you save solutions and projects, this selections are also persisted. Nice!
Now, how can we build an entire solution or a specific project? Glad you asked. Please take a look at the picture below and follow the numbers:
First, for each project at a time, check the Project tab and select the corresponding values for each field. In particular for this example, we need to set the build/copy actions and indicate the correct path to copy/move the asset files. For now, we disregard the Group Id field and the writers grid since we have only one writer we can use at this moment and thus we have no use for the former.
Second, we indicate which nodes among the containers, folders and raw files must be included in or excluded from the build process by checking/unchecking the respective checkbox.
Third, we select the correct writer for the project ("Default Writer") for the compilation profile to use ("Debug", as shown in the picture above).
Fourth, we select whether to build the entire solution (that is to say, all projects) or one project (the one shown in the Project tab). Also, we indicate the target compilation profile (the one that corresponds to your game's executing assemby, as compiled in Visual Studio, Xamarin Studio, Eclipse, Netbeans or other).
Having done that, we also need to indicate for the solution whether we want our asset files copied or moved to their final location ...
Then, we are ready to go. So all we need to do is compile the solution or project by clicking the "Build" button (the arrow in green).
You can also build the solution or project using menu options, "F5" for the entire solution or "Control + F5" for the selected project.
Now, what result shall we obtain for our example? To see that, we pick one of the projects in the solution explorer and open its folder with the "Open In Explorer" menu option, say, the iPhone.
You will get as an asset file a copy of the image sized 320x200 texels. And believe me when I say that if we built the entire solution (or only the Windows project) we also get the image sized 640x400 texels as an asset file located in the path corresponding to the Windows project.
But this isn't all we get as the picture below shows:
The Ape mantains a repository on the corresponding path for our solution, but is also moves/copy the obtained files with the correct path structure to the location you specify as an output folder, adjusted for the corresponding compilation profile. Since we said we wanted all our asset copied, the "local" repository keeps a copy of all asset files. Otherwise, no local copies would exist.
Again, when we compile the solution we also obtain the asset for non selected projects -provided they are alos marked for build + copy/move actions.
Now, when your game expects a file with a specific format (other than public ones like png, jpg, wav, wmv, and so on so forth) and or a specific file extension, then the above example is not useful for you. Therefore, for the following example I'll use a Texture2D importer and a XNA-like writer for a Monogame project. But please remember that you can use the APE for any game engine not related to XNA/Monogame, provided that the corresponding import/write units are plugged into the editor.
So, allow me to introduce you to a nice feature that the APE has: clean solution/project.
Both operations are similar, being the only difference that cleaning the solution will clear the content of all projects. This operations must be used with caution since they will delete the entire content of the folders indicated in the corresponding lines and not only raw files and nested folders. So before pressing start we should check that the paths are right. You can always cancel the operation by clicking the cancel button or by closing the window -in case you need to. And you can indicate whether to clean one folder (the local folder or the output folder), both folders or none. This is indeed a handy and powerful feature, don't you think?
Ok, after cleaning the solution and adding the corresponding import/write units to the editor we are now able to reload our solution and once we get it, we need to get something like this:
In order to get it, first we need to select the only raw file we have on the Windows Project. Then, we need to select the category "Textures" (1) and finally select the importer named "Xna Texture Importer" (2), which in this case is selected by default. As you can see we get some information about the importer and, in this case, a couple of read-only properties ("Group Id" and "Is Source File Also Copied ?").
As a result of the above we can now realize in practice how the Group Id field on the Project tab can be used (3): a value of zero indicates that we want to target XNA/Monogame's HiDef profile and a value above it the Reach profile.
If we expand the panel with the properties for the 2D Texture Processor we'll get:
I won't explain each of the fields you see there. Some of them are similar to what we had on XNA's CP GUI but there are some additional ones -which I believe speak for them-selves. All I can say is that this is not a mock-up; in fact, it's a real processor in alpha stage currently consuming WPF's bindings for WIC. During the campaign at IndieGoGo I'll give more details about this.
After tweaking some of the parameters, let's have a look at the formatter:
Nothing to do here. The "Xna Binary Formatter" will give the proper format to the asset data but with one difference for those of us accustomed to XNA's CP (given the way I've implemented these import/write units): the XNA's header for the asset file is not included as part of the format. That will be added by the writer later on. Needless to say that you can design your import/write units so that the formatter includes the header instead of the writer, which is fantastic given that it shows how flexible the APE really is!!!
Ok then, and please again follow the numbers, before proceeding to compile the texture asset for the Windows project we'll need to get something like ...
First, we select the Window project.
Second, we need to set the proper writer for the compilation profile we are going to use (in this case, for "Debug").
Third, we need to select the "Normal" compression mode on the Writers panel instead of the "Automatic" one that is shown in the picture above. Why? Because I haven't implemented yet the so called LZX compression -which is a real pain, believe me- or any other compression for the writer.
I'd like to add a side note here: do you notice the data displayed on the writer panel for the Xna Writer? (default, version, etc.) In particular check the following three: "Writes checksum", "Requires password", "Encodes Data". These fields if marked as "Yes" indicate that the writer May or May Not do the associated task (depending on whether is activated manually/automatically as implemented by us), like calculating an writing an MD5/SHA checksum somewhere into the asset file, adding password protection and or encoding/encrypting the asset file. And if marked as "No" then the writer does not support that action.
Fourth, and this is really important: we need to save the solution!!! (this is required to apply changes)
Fifth, we need to indicate that we're going to build only a project (the selected one) for the "Debug" compilation profile.
Finally, build the assets by pressing the corresponding menu option, button or keyboard shortcut ("Control + F5"), being the result in the local repository the following:
This is a well-formatted xnb file with pre-multiplied alpha, a mip-mapped chain and its top-most texture resized to the nearest power-of-two value for 640x400 texels (I leave the answer to the latter as homework for you). Since this asset file is not LZX-compressed, its size on disk is rather high. Again, a copy of this file is located on the output folder that the XNA/Monogame solution uses.
Finally, if we run the game's solution with a line like the following within the method of the LoadContent operation ...
this.texture = this.Content.Load<Texture2D>("textures/backgrounds/bkgClouds");
... and the corresponding one on the Draw method, as shown in the trailer for the APE, we'll get something like this on a WindowsGL-targeted game using Monogame (and please don't ask me "why do you need mipmaps for this example?"):
Enough said!
In the following parts we'll be getting into more technical stuff.
Cheers!
~Pete
