Palette Lighting API

[michael-fadely]

As mentioned in other issues (such as #20), the Dreamcast mods would benefit greatly from an API allowing them to control palette selection and lighting parameters manually. With this issue, I intend to outline all the functionality required by such an API to determine feasibility and implementation method.

So far, we know that the following would be a great help (if I've forgotten anything, let me know @PiKeyAr):

• [x] LandTable specular toggle (see #20)
• [x] Palette selection (expose LanternInstance::SetPalettes)
• [x] Separately-addressable palette selections (implement and expose LanternInstance::SetDiffuse and LanternInstance::SetSpecular)

As a bonus, the following would be nice for otherwise custom palette handling by misc. mods:

• [x] Palette file overrides (provide a callback interface so that a mod can indicate that it has a suitable replacement)
• [x] Expose d3d::SetShaderOptions for toggling fog, lighting, alpha, blending, etc.
• [ ] Implement explicit multi-palette support (e.g. Sky Deck multi-palette)

Some more ideas from @PiKeyAr:

• [x] Possibility to blend between diffuse A/specular B and diffuse A2/specular B2 without touching other palettes
• [x] A "disable built-in vertex colors" switch for objects described in #50. This isn't material-specific though... Basically anything that loads a non-level PVM/texlist has all its vcolors nullified if this is on.
• [x] A "force default material color" switch. Basically set the material's R G B to B2 if this is enabled. Or better yet, have this on by default and have a "use built-in material color" flag for special cases.
• [x] Parse only the first material in the model to determine whether the model ignores specular.
• [x] Parse specular color 0x00000000 as "ignore specular".
• [x] The "environment mapping on -> force object specular" condition is only getting in the way of accuracy at this point, and I suggest removing it or making it optional (disabled when the landtable specular switch is on).
• [x] White diffuse+specular (currently implemented via manual palette selection, sometimes with modified PL files)
• [x] If a material doesn't have the "use texture" flag, it doesn't get specular applied.
• [x] Material overrides that persist across PL file changes (Sky Deck)
• [x] Expose the alpha rejection value so that a mod could change it in real time
• [x] Light direction override
• [x] Palette override that works similarly to set_diffuse/set_specular but replaces the entire diffuse/specular palette with a specified color
• [x] Blending between a palette and a specified color
• [x] Adding a specific color on top of an existing palette? (Egg Viper)

[PiKeyAr]

Will palette selection allow me to hijack any material?

I was thinking of something like this: one bit in the unused material flags is picked up to tell whether custom palette selection is enabled or not. If it is, have the mod check a custom array that contains the materials and palette indices they need to use.

If the above is not possible, I guess we need to go back to the idea of using the unused material flags to indicate the palette pair number or something like that.

[michael-fadely]

Honestly, that could work. We could even take it a step further. For example, a single unused bit in the material flags could indicate that a callback is to be run, so all mods that registered a callback have a say in what to do with that material. It would be first come first serve though; the first to say "I got this, don't ask those other guys" gets to control the outcome.

[michael-fadely]

Fixed: no texture (rhino tank etc), sweep, and material specular alpha functioning as ignore specular.

[michael-fadely]

I've updated the checklist to include explicit multi-palette support. This would enable specific effects like the fading used in Sky Deck to mod developers. It will be a challenge to implement, but it would be very beneficial for Dreamcast mod accuracy and coolness factor. It would also help with material callbacks and such. As it stands now, Sky Deck tends to override changes made using the material callback system due to its multi-palette nature.

[PiKeyAr]

I've partially figured out how the game determines whether a material has forced white diffuse. It's absolutely related to the "ignore light" flag. Case in point: Egg Carrier model in Sky Chase 1. All objects with white diffuse that are part of that model follow this rule: if there's a material with "ignore light", all materials after it (only after, not before) have forced white diffuse. Another example is the palm trees near Tails' house. The trunks have white diffuse because their material is listed after the leaves, which ignore lighting. There are likely more conditions involved in this, because in Final Egg there is a model with several materials ignoring lighting, but white diffuse is forced only after the last one.

[PiKeyAr]

I've been running into a minor issue, but it's been pretty consistent so I thought I should report it. If an object is replaced in the mod like this: (NJS_OBJECT )0xwhatever = object_whatever; Then object_whatever's materials are parsed independently and the first material specular thing doesn't work with it.

[michael-fadely]

That's an interesting bug. It shouldn't change anything as long as the pointers to the materials are the same as the ones referenced by the models used in that object.

[michael-fadely]

Arbitrary palette index blending has been implemented. I'm considering the api stable enough to use, so I've merged it into master. After the next stable release, I'd like to implement explicit multi-palette management (e.g Sky Deck), and allow greater than 2 palettes for blending which would be addressable by using blend factors greater than 1.0f (Pretty straightforward, right?). At that point I'll consider it feature complete, ignoring of course the addition of overrides required for the accuracy of other Dreamcast mods.

[PiKeyAr]

A couple of new requests:

• Palette override that works similarly to set_diffuse/set_specular but replaces the entire diffuse/specular palette with a specified color - would allow to fake SA_ONE blending by calculating fog color in a specific spot and adding it as specular color - that already works, but the option would be still very helpful for white diffuse.

• Blending between a palette and a specified color - would allow to get rid of custom PL files entirely for such effects as Casino pinball room entry, dark room at the start of Froggy hunt cutscene, Egg Viper explosions.

• Light direction override - would allow to fake the SL Lights system - this will be unnecessary if the actual SL lighting is implemented (which is hard to fake using palettes anyway). I think the light direction override is already implemented though.

[PiKeyAr]

Re: White diffuse, I've almost figured out when it happens but at this point it looks inconsistent and honestly it's probably a fixed function pipeline bug like you said. So I'll be implementing it semi-automatically or manually for each model via the API. I don't think any other mods or vanilla SADX would benefit from white diffuse, so this "feature" of the original lighting system doesn't have to exist in this mod. I would really appreciate the function to replace a palette with a specific color though, not only for this "effect" but for other DC things, too.

[PiKeyAr]

I've added several new functions to the API related to replacing palettes. It should now be possible to replace a palette with a specified color, a color array, or a mix of an existing palette with a specified color.