Assignment Goals

The primary goals of this assignment are:

  1. Create a UE4 Plugin from scratch.
  2. Create a UE4 object importer.
  3. 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.

Bucky Ball Volume Texture Pane

Details

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.

Use this mhd header file and this data file for testing*.

Create a project

  1. Create a Basic Code C++ project (with no starter content) called assn5.
    • As usual, put the project at the top level of your git repository

Create the Plugin

  1. This time you will start from a Blank code plugin.
  2. 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.
  3. 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
  4. 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 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

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.

Grad Students

Grad students must complete one of the extra credit features. The feature completed for grad student credit can be submitted late. Since one feature is required, grad students can receive a maximum of 15 points of extra credit for the other three features.

Submission

For full credit, you must commit multiple times during your development.

Add an 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).

Push to your repository, and tag your final commit with an assn5 tag.