The primary goals of this assignment are:
- Create a UE4 Plugin from scratch.
- Create a UE4 object importer.
- Get experience looking through other plugin code and engine source as a strategy for working with a large codebase.
For this assignment, you'll be creating an new importer to create a UVolumeTexture object from a file. The importer will load files in a subset of the MHA/MHD format. This is a simple uncompressed format supporting both image and volume files. It consists of a simple text header describing the file contents, coupled with an uncompressed binary array of data, either embedded in the same file (typically given the mha extension) or in a separate file in the same directory (typically given the mhd extension).
This is the contents of the bucky.mhd file, with comments (not in the file).
ObjectType = Image # always the first line, identifies this as a valid image file NDims = 3 # 3 for volume textures, 2 for images DimSize = 32 32 32 # size in each dimension (read this from the file, do not hard-code 32) ElementNumberOfChannels = 1 # number of color channels, up to 4 = RGBA ElementType = MET_UCHAR # data type for each color element, in this case, unsigned byte ElementDataFile = bucky.raw # must be last: file name in the same directory to find the data
Your importer only needs to support one color-channel volumes with unsigned byte components and the data in a separate file (like this one). You should ignore header lines that your importer does not support, but report value errors for header lines you do support (so if Dims is anything but 3, or if any of the dimensions are zero or negative). Report errors using UE_LOG so they will show up in the editor Output window.
This assignment provides only rough pointers to where to find examples and class declarations you will need. Part of the assignment is for you to get more comfortable searching through the source to find things like this.
Create a project
- Create a Blank C++ project with no starter content called
- As usual, put the project at the top level of your git repository
Create the Plugin
- This time you will start from a Blank code plugin.
- Add an asset load factory class to your plugin.
- Classes to load assets are derived from UFactory.
- To load from a file, you should override UFactory::FactoryCreateFile function. Find examples in the engine and engine plugins.
- To avoid undefined symbol errors, add the module for UFactory (look at the UFactory API macro for the module name) to your plugin's Build.cs.
- Use Formats.Add in your class constructor to tell UE4 that you handle files with the mha and mhd file extensions.
- You can create and return an empty UVolumeTexture object to make sure it is working
- At this point, (even before your importer does anything), you should be able to drag an mhd file into the Content window and confirm that your importer is run.
- Load and parse the mhd header file
- Look at FFileHelper for file loading functions.
- Look at FString and FCString for simple string matching and string-to-integer conversion functions.
- Log a useful message and return nullptr on any loading error
- Load the data
- FPaths has some helpful functions for splitting a file name into the path, base, and extension
- Load the data into the UVolumeTexture
- UTexture.Source.Init will initialize the size, format and data
- The G8 texture source format will work for 1-channel UCHAR.
- Set UTexture.SRGB to 0, since this is not color data
- Call UTexture::UpdateResource to update the UVolumeTexture object with the loaded data
Extra credit is only available if you submit by the original due date. For five points each, add one or more of the following features. Create and submit test files for any features you add. You can create these procedurally with a simple program, or for 2D textures, use a tool like ImageMagick to generate a raw file for an existing image, then create the header by hand in a text editor.
- Support for 2D textures (with Dims = 2 and only two numbers in the DimSize line).
- Support for 1, 2, 3, and 4 channel data. For some sizes, you will have to copy and convert into an RGBA buffer on load. For example, three-channel data could put the three data channels into RGB and set A to 1. Two-channel data could be put into R and G, with B=0 and A=1 (assuming it'll use the RG8 GPU format), or could have one channel copied into all three of RGB and the second channel copied into A (assuming the two channels represent intensity and opacity).
- Support for MET_UFLOAT data.
- Support for ElementDataFile = LOCAL. For LOCAL data, this line is followed by a single \n character, then the binary data is embedded directly in the mha file.
For full credit, you must commit multiple times during your development.
assn5.txt. Tell us what works and what doesn't, and anything else you think we should know for grading. Include two screen shots of the UE4 editor pane for your VolumeTexture object editor with only the red channel selected. One should be in "Depth Slices" view mode, and the other in "Trace Into Volume" view mode.
Make sure your
assn5.txt file tells us if you attempted the extra credit, and if so, which parts, and where to find the test file(s), and screen shots showing your results.
Push to your repository, and tag your final commit with an