Comprehensive tuto about ColorizingDMD

Hello and welcome friends who would like to become ROM-colorization authors!

As you perhaps know, I've just released a new file format called Serum (aka cRom) for the colorization of our VPX ROMs.

With this format, I needed to code an editor that would be as simple and easy as possible to make people interested in it.

This editor is open-source and may be downloaded here: https://github.com/zesinger/ColorizingDMD/releases

The second most important things to make this format a success is a good tutorial and here it is.

Throughout this guide, I will use several different text colors:
- I will try to highlight the subject of the paragraph coloring it in red
- A text in blue will explain things that are non-needed for the understanding of colorization, but will give extra information if you want further details.
- A text in purple will give you hints to avoid pitfalls in colorization.
- A word in green is a vocabulary, the first time I'll use this word, I will put it in green so that you know what this word will mean later on.
- A keyboard sequence in orange is a keyboard shortcut.




IMPORTANT LEGAL NOTICE:

1/ Everything from my cheap real DMD "ZeDMD" to my "Serum" (aka "cRom") file format and its editor "ColorizingDMD" are open-source and subjects to the same license, GPLv2.
I DON'T EARN a thing from them (except perhaps some kind feedbacks and a place in the vpin world ), not even a single Euro!
My ZeDMD may be sold by any reseller who wants to but I don't want to get anything AT ALL from that!

2/ Thus, if you create a colorized ROM Serum with ColorizingDMD, you must accept the fact that you will share it for free.
As of now, the Serum format is only available for virtual pinball emulation, but I accepted that Markus Kalkbrenner integrates the ZeDMD and, perhaps later on, the Serum to its open-source and DIY PPUC which may bring the Serum format to the real pinball machines!
So, as a colorization author using Serum, you must accept to share it for free for real pinball machines too.
Asking for donation is possible and I even encourage users to donate to colorization authors for the huge amount of time they spent on it!
Moreover, if a third party is providing your Serum file, he or she CAN NOT provide it in a pack with other files and MUST credit you and provide a link to the website where you posted the file.

3/ It is important to me that all the things I code or create remain in the open-source DIY side, so any concept from my code (like colour rotations or sprites) CAN NOT be used in encrypted/protected /closed-source code/file format but freely for any open-source project as long as you credit me!

 

OK OK, for several hundreds of thousands bucks, I could be corruptible...


Before we start the tutorial, let me thank @dtatane, @ebor, Kraken (discordapp.com/users/269602624938967052) and @peskopat:

- for their active beta-testing and bug reporting.
- for their  ideas proposed over and over!

- for letting me use their WIP on Tron and Scared Stiff to promote the Serum file format on many forums, facebook groups, etc...

Let me first tell you that @dtatane, author of such beautiful colorizations like Junk Yard, Champion Pub, Last Action Hero and the very first Serum Scared Stiff propose video tutorials here https://www.youtube.com/playlist?list=PL_BgMMKhwOKJ9EieULq_tjClotEdiR6MO! Thank you buddy.



I/ Ingame process

You can not avoid many pitfalls while colorizing if you don't understand how it works ingame, so I'm gonna first try to explain the different steps.

1/ Preamble


a/ PinMame is the emulator. It reacts to stimuli like "The ball bumped into this.", "The ball rolled through this.", "The player pushed this button.", etc... calculating the score and many other things, knowing which player is playing now and generating with all this information a frame.

A frame is a 128x32-pixel image (rarely 192x64 or 256x64) displayed on a screen called the DMD as it used to be a dot matrix display.

The initial ROMs taken from the real pinball is either in 4 colours (we will call it colour2 bits as 2^2=4) or in 16 colours (colour4 as 2^4=16) which colours are shown on DMD as a shade of orange.



With the Serum format we will convert it to colour6 so with 64 colours (2^6=64).



[Extra info]
Why to choose paletted colour6 and not RGB format that would allow to choose a different colour for each pixel?


A paletted colour6 frame is made of:
- A 64-RGB-colour palette (one byte per component Red, Green and Blue), so 64*3=192 bytes
- A 128x32 image with 6 bits per pixel (value between 0 and 63), 6/8 of a byte as a byte is 8 bits, so 128*32*6/8=3072 bytes
Total: 3264 bytes


A RGB frame is made of:
A 128x32 image with 3 bytes (the 3 components) per pixel, so 128*32*3=12288 bytes


For a PC, 12288 bytes is peanuts to display on a Virtual DMD, but when it comes to real DMD, this is another kettle of fish! This frame must be sent to the device through a serial (USB) port that is really limited in the transfer speed, if I take the example of my ZeDMD, it uses a CP210x or a CH340 serial chip that are limited to 921600 bauds, that means 921600 bit/s or 115200 byte/s. For the colour6 frame, we have 115200/3264~35fps, for the RGB frame, 115200/12288~9fps!


When you know that some extra transfers are needed and that the baud rate is a maximum, you may expect 25fps in colour6 and 6fps in RGB.


So I decided to stick to something smoother. Adding to that the fact that we are drawing on a really small image (128x32), I think that's enough!
[End of extra info]


b/ Freezy's DmdDevice.dll (placed in the "VPinMame" directory, activated ingame with the F1 key and "Use extrernal DMD (dll)"checked) receives the frame and must convert it. It means:
- colorize it if there is a colorization ROM file in the "same_name_as_the_rom" subdirectory of "VPinMAME\altcolor". You activate it ingame with the F1 key and checking "Colorize DMD (4 colors)".
- resize it if the initial frame has not the same dimensions as the destination device(s)
- send it through USB serial communication to any activated (in the DmdDevice.ini file) and connected destination device.

The first step is using the file you are proudly going to create!

c/ Destination device (Virtual DMD, ZeDMD, Pin2DMD, PinDMDv3) receives the data and does the necessary modifications to display it on the screen or dot matrix display. But that's not really interesting for colorization.

So in the next 2 parts, we will describe the ingame process for the colorization (the first part of the b/).

2/ First step: Comparison (we could call it "Identification", too)

So you think that ColorizingDMD is just another Paint-like software: you have one shade-of-orange frame, you create your 64-colour palette and paint the frame with it and that's it?



It would be so if everything was as simple as a static frame like:



Nothing special in it, it will always appear this way with no modification at all! So the program only need to compare the inbound frame (= sent by PinMAME) to this one and say "OK, we have found the right frame, let's display the colorized version of it!"

But now let's look at this frame:



We have "90" and "8,000,000" that may be any other different values from one gameplay to another and even in the same gameplay. We call them dynamic content. There is an "infinite" number of combinations, you can not draw this frame for every values so that the program will check and find the right one.

To cope with that, we are going to use comparison masks! It is really easy to understand, for comparison step, you are going to compare only the static part of the frame so the part where "90" and "8,000,000" are drawn will be masked (= ignored) for comparison.
The first task will be to design these masks so that the program can't mix any frame with another one, only comparing its static content.

You must know that if the Comparison step ingame gets an inbound frame that does not match with any frame available in the Serum, nothing happens, the previous identified frame remains displayed until a new identified one is received.
If it matches with a frame that has not been colorized, the original un-colorized frame will be displayed.

There are several pitfalls we must avoid, we'll see that when we'll really describe the Comparison step in ColorizingDMD.
[Pitfall warning]
But be aware that the comparison step may be CPU demanding ingame if we have too many comparison masks. The software provides up to 64 comparison masks, but less than 30 for the whole ROM would make it more efficient. The key is to re-use your mask as much as possible even for frames that does not seem similar.
[/Pitfall warning]

3/ Second Step: Colorization

Things are really easy: we have an inbound 4-or-16-shade-of-orange frame, the Comparison step converts it to an identification number (= ID) in the list of frames we have in the Serum. Then we know that we must display the colorized frame #ID.

... ... ... ...



"... Wait a minute! but what about the dynamic content, you said in the Comparison step that we can not draw every frame for every dynamic content like scores, number of players, ball number,... so how are we going to colorize this part of the frame?"

We are going to generate the dynamic content colorization in real time swapping the initial 4-or-16-colour palette with 4-or-16-colour sets we create from our 64-colour palette.

So this frame:



with 2 scores to the left and the "2" as dynamic content will look like this once colorized this way:



5 sets were used for the "2" as it is mono-colour in the VpinMAME and the result is a shade of grey in the colorized frame. We'll see how to do that in ColorizingDMD.

4/ The sprites

This is a specific type of dynamic content I added to the format as a request from @dtatane. It doesn't solve every particular situation, but in this short excerpt showing the video mode of the table Junkyard https://youtu.be/3HcVr_hfh0U?t=103, we see the perfectly appropriate case.

As you see, this scene is complex as the man with his gift is running, moving from left to right in the frame. If we use dynamic colorization, we must select the whole scene wherever he may go, resulting in a ugly scene where the colour-swap sets for the man will be the same as the ones for the gift, the fence, the dog...

You must know that the dog is perfectly synchronized with the fence movement, if you ignore the man in the scene, there will be only 7 different frames:





So we can colorize 7 frames covering all the situations for the dog and the fence. Then, the man will be considered as a sprite, i.e. a moving object that should be find in the whole inbound frame and colorized where it was found in real time.


OK we know enough to start using ColorizingDMD.

II/ ColorizingDMD

The way ColorizingDMD is designed is faithful to the ingame process with its 2 steps (Comparison mode and Colorization mode) and seperated Sprite process.

It mainly consists of 4 different windows: one for the frames, one for the sprites, one to import images and one for the backgrounds. A fifth (text) one is available as a log (mainly for debug purpose, you may ignore it).

I decided to propose a program with no menus and submenus, but instead one toolbar with all the functions needed in the current mode we are working on. You will use 5 different toolbars: one for the Comparison mode, one for the Colorization mode, one for the Sprites, one for the images and one for the backgrounds.

But before starting the program, you must have some files called dumps to provide the different frames available ingame.

1/ Getting the dump files

These dump files are just huge text files with, for each frame, a timecode followed by hexadecimal numbers representing the number of the color of the pixel in the orange shade.



To get them, either you generate them or you get them from some people used to do this.

a/ Generate them

For graphical ROM:
- in the directory "VPinMame", to create a directory "dmddump" (caution: it's easy to mix "d"s with "p"s and then you don't understand why it doesn't work)
- ingame, press F1 and check both "Show DMD Window" and "Use external DMD (dll)". Click "OK" to confirm.
You may have to restart the table to make it work and then everything that is displayed on the DMD is then dumped in a file called "name_of_the_rom.txt" placed in this "dmddump" directory.

For alphanumeric ROM:
- In your freezy's dmddevice.ini file, check that the "[rawoutput]" section has "enabled = true"

What is difficult for a complete colorization is that you must get ALL the frames possible for ALL the situations (for the static content only, of course).
If you restart a table that already has a dump in the "dmddump" directory the new frames will be appened at the end of the file, so the previous content won't be deleted.

But you may cheat: in Visual Pinball, there is a debug mode that you can trigger:
- up to VPX 10.7.X: pressing Esc ingame and clicking on "Debugger/Intera.Ed". Then you check "Ball Control".
- from VPX 10.8.X on: pressing 'D' key.

Now play normally... except that you may control the ball with your mouse and then bring it wherever you want to trigger any event that will be recorded in your dump file!



b/ Get them from someone else

In the forum VPUniverse, there is a specific topic about the dump files here https://vpuniverse.com/files/category/94-rom-frame-dumps/
Try to find the one that you are looking for or ask to active members in the topic like Terranigma and you could get something quickly and complete!

2/ User Interface general presentation


Just to be sure we are using the same language, let's see the way the windows are composed. Here is a capture of the Frame window:



At the top, the title bar (framed in red) gives some info on the ROM name, the current displayed frame number and the total number of frames in the ROM.
Below, the toolbar (in blue) gives you all the tools you need to edit your ROM. Caution: I've been warned that if the "Scale and Layout: Text Size" inside the Display Settings of Windows is set to more than 100%, the fulltoolbar may not be displayed. You may resize the window, but...
Then, the current displayed frame (in green) is the place where you design your masks and frames.
The frame strip (in purple) to change the current active frame.
Finally, the help bar (in orange) at the bottom provides some help about the button you are over with your mouse button.

The Sprite window is composed exactly the same way, except that you see both the initial and colorized sprites at the same time.



The Image window is even simpler, just an image loaded and a toolbar:



Finally the Background window is made of a toolbar, a background displayed and a background strip:

3/ Common commands

In the main (or frame) window, at the very top left, you can switch from day to dark mode with the button .

To switch between the 2 modes Comparison and Colorization in the Frame window, you have the left button or you can press Ctrl+M.
In the main (= frame) window, for both modes (Comparison and Colorization), you have access to these tools:

a/ The frame, sprite strip or background strip




The lower element in both windows is called the frame (or "sprite" in the Sprite window or "background" in the Background window) strip.
The frame and background strips have a slider at the bottom as the number of frames may reach more than 50000 for frames and several thousands for backgrounds. So you may quickly navigate with it through the frames.
Some more information are displayed on the frame slider:
- a white dot on the upper part of the slider shows where is the current displayed frame
- a gray dot shows where are the the other selected frames as you may select up to 1024 frames at the same time
- a green dot on the lower part of the slider shows where are located the similar frames to the current one displayed (we'll see that later)

Above each frame, you may see 2 or 3 numbers:
- The left one is the frame number. If it is green, it is a similar frame else it is grey. It is similar for the backgrounds.
- The middle one in purple is the bookmark number this frame is part of (we'll see that later).
- The right one in yellow is the length of time the frame was displayed when the dump was done. It can be a useful information to know if this frame really needs to be colorized or if it may be deleted.

Then the frames themselves have a frame which is:
- white if this is the current displayed frame
- blue if this is one of the other selected frames
- red for any other frame.

To select several frames, do as usual:
- Use Ctrl to keep the previous selected frames and click on others to add them
- Use Shift and click on a frame so that all the frames between the previous selected and the one clicked will be selected (up to 1024!)
- You may use both Ctrl and Shift to keep the preceding frames selected and to add a range of frames.
- If you click on an already selected frame, if it was the one already displayed, all the others selected are unselected, if not, the selection remains the same, but the new displayed frame is the one clicked.

Most of the actions done will be applied to all the selected frames.

For the sprites:



The white contoured sprite is the selected one... Nothing else to know.

For both strips, you can navigate moving the displayed frame/sprite with the direction left and right keys or you can use the mouse wheel to move through the frames/sprites without changing the displayed frame/sprite. Pressing Shift will jump to the next page.

Let's explain the toolbars.

b/ Disk actions

• Start a project using to load the first dump file of the project. A window opens and then you just have to browse and find this file. This action may take a while as all the frames are compared to each other to avoid duplicate.
  
• Add extra frames to your project, if the inital one was uncomplete, using . Browse for the extra file. The duplicate-frame check is done once again.
  
• Open a project (.cRom + .cRP files) using .
  
• Save a project using . I suggest to save as soon as you have started the project with as loading a project is almost instant but  loading a new dump file may take some minutes.
  You may do the same action from the Sprite window.
  The standard shortcut Ctrl+S may be used for saving.
  If you press Shift while clicking on or pressing Ctrl+S, a window opens to let you choose which directory to use for the saves. I suggest that you always do that the first time you save a project. You may check on the log window that your project has been correctly saved.
  

c/ Bookmarks actions



With a project that may have more than 50000 frames, you may spend a lot of time navigating between frames. To save some time jumping directly to a specific frame that starts a sequence, bookmark this frame.

• To bookmark a frame, display it, type the name of the sequence in the upper edit box then press . The bookmark will be added in the list below.
  Then all the frames that will be after this frame but before the next frame which is the first for a bookmark will be considered part of the sequence.
  In the frame strip given as an example in 3/a/, the frame 143 is the first of the sequence #2 ("Flynn's") in the list, all the frames left of it (140, 141 and 142) are part of the sequence #3 ("Tron") in the list and the frame after (144) is part of the #2.
  
• To remove a bookmark, display a frame that is part of it and press . Caution: it doesn't delete the bookmark pointed in the list box, but the bookmark the currently displayed frame is part of! If this frame isn't part of a sequence bookmarked, the action is ignored.
  
• You can reorganize your bookmarks using . It then displays this window
  
  
  
  Select the Bookmark you want to move, click on "UP" or "DOWN" to move it. Just move the mouse out of the window to hide it.
  Use the button "ALPHA" to automatically sort the sections according to their name.
  

d/ Undo/Redo

Come on, do you really want me to explain what the 2 buttons Undo/Redo are for?
Just be advise that some rare actions can not be undone/redone (these commands are really memory-hungry, reason why you can not select more than 1024 frames at once) and you may undo/redo up to 16 actions.
Of course, the standard keys Ctrl+Z and Ctrl+Y are working!

4/ Comparison mode




If you are an artist, this step of the creation of your Serum will certainly be a chore! All the more because it must be done with caution to avoid to make the program identify the wrong frame ingame.

a/ Choosing your mask



You choose a mask for identification of the selected frames in this drop down list.
If you have already drawn some masks, they will appear in purple on the current displayed frame. So the part not "purpled" is what your frame will be identified with.
If the frame you are on has no dynamic content, let the mask ID in the listbox below "Mask" to "- None -" (default).
Otherwise, every mask ID in the list is preceded by a checkbox, if this mask is used by at least one frame, the box is checked, so you know which ones are free to draw for your specific dynamic area.

If you clicked on the button since the last change of displayed frame and modification of the current mask, some extra values are displayed for the existing masks: "same frames x, with shape mode y" where x and y are the number of frames that would be identified as identical if you choose this mask (x without shape mode, y with shape mode). That's an aid if you want to re-use some masks as much as possible (see below).

[Pitfall warning]
We've already seen why it is a good practice to reduce as much as possible the number of masks, so always try to apply the existing masks to check if it fits your needs for the frame you are on.
Perhaps you can redesign a mask so that it still works with the frames it was initially drawn for and, with these modifications, it now works with this new frame...
You must understand that you don't need to let the whole static content unmasked for the frame to be identified.


Let's look at an example with these 3 frames:








These 3 frames are really different, but you can use the same mask for detection.
[/Pitfall warning]


b/ Drawing you mask



Now you have chosen your mask ID, you need to draw the mask.
The 3 drawing-tool-button icons are quite self-explanatory: select you mask point by point, with a whole filled rectangle or using the magic wand (selecting a full continuous area with the same colour).
So Left mouse button is used to add points/rectangles/"magic wand areas" to the mask and Shift+Left mouse button is used to remove from the mask.
Ctrl+A will select all the frame for the mask.

Ctrl+D will unselect all the frame for the mask.
The button is used to invert the selection, so everything selected will be unselected and vice-versa.

The Shape mode checkbox needs some explanations:
In a 4-or-16-color frame, the color number 0 is black and often used as the background, all other colours are used to draw elements. The Shape mode only makes the distinction between colour 0 and the other ones.
Let me show you the appropriate situation with the Jurassic Park table. Look at this frame shown when starting the table:



Let's consider the "TESTING T-REX DIAGNOSTICS" was not there and we had to use the "PLEASE WAIT" for comparison.
You see some clear dots and some dark dots. They are changing all the time and seems to be placed randomly, so it is impossible to make a comparison for every case. If we check the "Shape mode" box, the inbound frame and the Serum frame will be compared as if they were:



So wherever there are dark or clear dots, it won't make the difference. Easy!

[Pitfall warning]
Concerning the comparison be careful that some static elements are not that "static". Look at this frame:




Here, the only "static" element is "CREDITS". But the whole line "7 1/2 CREDITS" is centered in the frame, so if we would have "7 CREDITS", the "CREDITS" wouldn't have been at the exact same place. In this case, we have no choice but to dump every cases (= every different position of "CREDITS")and colorize them separately. As the digits have all the same width in pixels there should be only 2 cases (with "1/2" and without it), so it can be solved easily, but don't be surprise if you have colorized a frame and it appears not colorized ingame as the not-really-static elements may have been shifted by 1 or 2 pixels.
[/Pitfall warning]

Don't be surprised, you'll have difficult times at the beginning if you are not used to it. But with a little training you will understand how it works.

c/ Same frames



This section provides information about frames that are identical once the mask is applied.



In the above screen, with the mask you see, ColorizingDMD find 163 same frames. So these frames are considered as identical because they have "PLAYER", "BALL" and "CREDITS" at the same place. As you already know, they are shown with their number written in green and in the lower part of the slider with green dots.
One thing you don't know is that you can navigate between these "same frames" using Ctrl+Left/Right. Doing so, you don't change the frame selection but the frame strip will scroll to show all the same frames in the left frame of the strip.

OK, what to do with these "same frames"? If you are sure that you don't need them anymore, you can click on and all the "same frames" (taking into account the mask) will be deleted!

[Pitfall warning]
You must do the "cleaning" action as late as possible, because you never know if a frame is not useful...
[/Pitfall warning]

The next level is which is used to delete all the same frames for all the selected frames.
The ultimate cleaning button is , it will go through all the frames and delete all the same frames.
[Pitfall warning]
Use that button with caution as you don't control which frame is the one kept and which are the frames deleted among a group of "same frames"
[/Pitfall warning]


The check box will let you be sure that the selected frames in the frame strip won't be deleted by these operations. It may be useful if, for example, you want to keep frames as a reference for your sprites, or any other reason.

d/ Delete frames

The button is as simple as its icon: you can manually delete the current frame by cliccking on it. That's all!

e/ Trigger ID



This is a feature requested by Nailbuster, coder of Pinup Popper:
If you are familiar with Pup packs, you know that each movie must be triggered at a specific moment of the gameplay.
So if you are designing a Pup pack, you may set a "D" trigger ID to any frame, so that when this frame is identified during the gameplay, a DXXX-notification with this ID.
Default is "- None -", so no notification sent, but if you need a trigger, just enter its value to affect the ID to this frame. If you want to remove a trigger ID, just click on the "X" button and the value will be changed back to "- None -". Easy...

f/ List the frames using a mask



This is a feature requested by @ebor to know which frames use a mask. Just select the mask number in the upper list then the lower list box will display all the frames using it.

g/ Set frame duration

is just what it says: in the frame strip the number in yellow is the duration in ms of the frame when it was dumped, but you may need to set this duration to any value that suits you. It has no consequences ingame as the colorization is displayed according to what is received from PinMame, but for the Freezy's DMD extensions test or for video importation inside ColorizingDMD, this value may be useful.

OK with all these tools and some training, you should be able to succeed in the Comparison step of your Serum creation



Now it's time to show your artist skill in the Colorization step!

5/ Colorization mode



I hope the first step has not killed the Vincent Van Gogh inside you, it's time to draw!



a/ Drawing tools



Once again, this is self-explanatory: you may draw points, lines, rectangles, circles, ellipses and use the magic wand as before. The box "Filled" is for rectangles, ellipses and circles. A red under-line shows the current active tool.
These tools will be used to draw, to select an area for copy, to select dynamic masks and line, circle and ellipse tools will be used for gradients.

b/ Copying



To copy part of the current frame to other frame(s), draw the selection with the Ctrl key pressed. A mask in clear blue will be shown as the copy mask. Ctrl+Left click to add to the copy mask and Shift+Ctrl+Left click to remove from the copy mask.

As a request by Kraken, if you press W while selecting your copy mask (so while pressing Ctrl), only the part of the frame where the colour is NOT 0 will be selected. Why? Often, 0 is the colour used for the background, so this way you'll only select the part of the scene that is drawn.

Another request by Kraken is the possibility to select all the pixels of the same colour in a frame. In magic wand mode, press and maintain Ctrl+Alt then click on a pixel in a frame and all the pixels of the same colour will be selected. Caution: it only works for static colour pixels, those which are drawn dynamically even if the result is the same colour won't be selected, it wouldn't make sense.
Ctrl+A will select all the frame for copy.
Ctrl+D will unselect all the frame for copy.
You may use the lower button to invert the copy mask.

Once the copy area is complete, either click on "Copy" or press the standard Ctrl+C. Then select one or several frames to copy to and either click "Paste" or the standard Ctrl+V to paste. As a request by Dtatane, if you press Shift while pasting, the copy will be done only on parts of the frame where the original frame is identical to the the source frame original frame (I suggest this video for complete explanations https://www.youtube.com/watch?v=Rcaxiiu866M). Finally use the mouse or the keys "2", "4", "6" and "8" of the numpad (without moving the mouse cursor) to place your copied area in the frame and left click or press "Enter" to complete the action. Caution: if the mouse pointer is out of the frame, only "2", "4", "6", "8" and "Enter" will work!

As requested by Ebor, if you maintain the K key while pasting (Ctrl+V or click on "Paste") then you do a mirroring of the copy selection horizontally, if you press the L key, you do a mirroring vertically, if you press both... you have nimble fingers!

Important: when you copy from one frame to another (or to others) the full palette and all the dynamic sets (we'll see that later) are copied too!

As a request by Boroka, is another button aimed at make you save some time: if a part of the original frame is identical at the same place in several other original frames, but the rest of the frame is different, select the common area (with Ctrl) then click this button. It will look through all the original frames if this part is identical and if so, it will copy this part of the colorization from the displayed frame. For a visual explanation, you may look here https://github.com/zesinger/ColorizingDMD/issues/43.

c/ Choosing colours

There are two 4-or-16-colour-set shown in the Colorization toolbar (the number of colours depend on the original ROM). They have not the same use, but you can do the same things clicking on 1 of the 4-or-16 colours.
There is one active colour, the one with a red frame.
You can change this active colour clicking on  to pick a colour directly on the frame. Once you've clicked on the pipette, you can do nothing until:

• You've chosen a colour to replace the active one
  
• You've pressed Esc or click again on the pipette to cancel the action
  

Left clicking on a colour in the 4-or-16-coulour grid will bring the frame's 64-colour palette



If there is a diagonal line over the colour, this colour is not used in the frame (only for static colorization, not dynamic).

• If you just left click on a colour, the colour previously clicked on the 4-or-16-colour grid will be replaced by this one
  
  
  
  
  
• If you right click on 1 of these 64 colours, the Windows standard colour picker window is shown
  
  
  
  Then you may choose a new RGB colour to replace the previous one
  
  
  
  
• If you maintain Shift while pressing the left mouse button on a color and releasing it on another color, you automaticly generate a gradient with the colours between these two colours (here the purple 40 and white 48)
  
  
  
  
• If you maintain Ctrl while pressing the left mouse button on a colour and releasing it on another colour, you define the colours used for the "Gradient draw" mode (we'll see that soon)
  

d/ Saving you color sets

The button opens the window:



where you can save 4-or-16-colour set for drawing.
When the current set of colours may be re-used later, just click on "Set" for a set not used and type in a name or short description in the edit box.
Just leave the window with the mouse cursor, the window will close and everything will be saved.
If you want to re-use a set, just click on the set in the "Sets" window and the active 4-or16-colour set will be changed.

e/ Drawing modes




There are 3 different modes:

• The "Monochrome draw" will use the active color to draw. Left click to draw with the tool. Shift+Left click to reset the area corresponding to the tool to the original frame color ID. I said "ID", because if the 4-or-16 first colours have been modified, the reset will be donne with these 4-or-16 first colours, even if they are not a shade of orange.
  As a request from Dtatane, if you click on a pixel maintaining the Alt key, all the pixels of the same colour will be painted.
  
• The "Color set replace" will use the left 4-or-16-colour set to replace the original colours of the frame with these one. If the original frame was:
  
  
  
  and our set is:
  
  
  
  if we draw a filled rectangle in "Color set replace" mode to the right part of the frame, we have:
  
  
  
  
• Finally, we have the "Gradient draw". For that special drawing effect, we need to have a copy selection drawn as the action will be done only in the copy area.
  Do not activate the Gradient draw mode before drawing your copy selection as this mode doesn't permit to use any other tool than the line and circle tools. So draw you copy mask then switch to Gradient draw.
  When we talked about the 64-colour palette, we've seen that using Ctrl and selecting a range of colours is used for this Gradient draw, once you've done it, the colours under "Gradient draw" reflects what you've selected and these colours will be used to fill the copy selection.
  Finally, you only need to choose your tool, either line tool for linear gradient or circle tool for radial gradient, then draw to define respectively either the orientation of the gradient or the center and ray of the gradient.
  Here is a video to show a complete use of the "Linear radient draw"
  
  
  
  And here is what Kraken did with a single radial gradient along with colour rotation (so this is a single frame!):
  
  
  
  You are amazing!
  

f/ Copying colours



These 2 buttons are used to copy colours from one frame to other(s). Select all the frames you want to copy the colours to + the one you want to copy from, be sure that this last is the displayed one, then push if you want to copy the current set only or if you want to copy the full 64-colour palette. That is useful for all the frames in the same sequence.

g/ Colour rotations



This is another cool feature of the Serum file format.

Once again, there is a limitation as the rotation is updated inside the DMD device code. So if the device doesn't implement it, the colorized frame will be shown but no colour changes. I implemented it in the Virtual DMD and ZeDMD code and can share the code explanations to any device creator.

You may have up to 8 colour rotations per frame.
This is really easy to use. When you click on the button, it opens the window:



Left click on the central white part for any of the line you want, it shows the 64-colour palette. Then do as you would do to create a gradient between 2 colours (Maintain Shift while pressing the left mouse button on one colour and releasing it on another one) and the colour rotation is done. You may now change the speed of the colour rotation entering a value in the right edit box. The lower the value, the faster the rotation.



Then you see the rotation in the displayed frame (it is not displayed in the frame strip as it would slow down the overall program).

As you can guess, the button on each line is used to delete a colour rotation.

h/ Dynamic colorization



We have already talked about this part of the colorization for the frames. When there is dynamic content like scores, ball number, ... that may be different for each gameplay or even inside a gameplay, we have no choice but to colorize it dynamically ingame.
As we have seen, this will be done swapping the initial colour set by another one we choose among the 64 colours of the frame.

With , you choose the dynamic set to swap with the original shade-of-orange set. You have 16 different sets for each frame.
You already know how to change the colors of the set. The button copies the drawing color set to the current selected dynamic set.

To draw the dynamic mask for the selected dynamic set, use the drawing tools on the displayed frame with the Right mouse button. Use Shift+Right mouse button to remove from the dynamic mask and to invert the current selected dynamic mask.

If you want to copy all the dynamic content (dynamic values on the frame + dynamic color sets) from one frame to others, select all the frames, display the one which will be the source and press . If you press Shift while clicking the button, the palette will be copied too.

Finally, you may use the "Spot" button to show you where the current dynamic mask is used on the frame.
The flashing purple line contours all the dynamic content, but if you push this button, it becomes red and then the area masked for the current selected dynamic set will be shown with a flashing purple grid.



Let's take an example. In this frame:



The "74" and "1,050,000" are dynamic content and they are drawn in the inbound frame with the 4th colour . So, in our dynamic sets, we only need to change the 4th colour to change in real time the colour of the dynamic content.

With this dynamic set:



if we draw (right mouse button) filled rectangles over the dynamic content, it will be colored this way:



whatever the dynamic content is (i.e. with different score or remaining hits).

What is the interest to have 16 dynamic sets? You may affect (= draw) the dynamic set as you wish on the frame, so you may draw with different sets on different parts of the dynamic content. This way, you can, for example, display your dynamic things with gradients.
If I create a blue gradient in the palette:



if we set the 8 first dynamic sets this way:

 
   


and draw with each set horizontal line by horizontal line, we colorize ingame the dynamic content this way:



Nice, isnt' it?
Of course, you can use different colours for the score and for the number of hits!

And if you mix that with colour rotation (because dynamic sets are affected by colour rotation):






But I'm sure you can do much better than that!

Unicorns are going to love it!




[Pitfall warning]
You may be tempted to overuse the dynamic content swapping as it may help to save a lot of time colorizing. Indeed, this way you may group more frames and have less of them to colorize, but:
- Doing this way the richness of the colorization is never as good!
- Dynamic colorization is slightly more demanding for the CPU
- Come on, you are here to show that you are an artist, take your time to express all your creativity!
Dynamic colorization is mainly here to deal with numbers, don't forget that!
[/Pitfall warning]

i/ Scroll Autofill


Requested by Dtatane: as this is quite recurrent in original ROMs to find horizontal or vertical scrollings, this option lets you colorized key frames where content is contiguous but doesn't overlap (it can, but this is not needed). Select all frames from one colorized keyframe to the next one then just press and it will detect any scrolling in the selection and auto colorize the remaining frames. You may check this video https://www.youtube.com/watch?v=T4RMrIz0Fhs

j/ Save frames as animated GIF

This is a function to proudly show what you did and sometimes to ask for help. Just select a contiguous group of frames you want to have in your GIF then press this button. At first use, ColorizingDMD ask for a directory for your GIFs. By default, only the colorized frames (with colour rotations) are shown in the animated GIF, but if you press Shift while pressing the button, the animated GIFs will show at the same time both versions of the frames.



Easy!

k/ Test your colorization like it will be ingame


is a wonderful button. With it, you'll see exactly how it will be shown ingame as it uses @freezy 's DMD extensions (as you should do to display it within VPX). For that, you need to have the 64-bit version of dmddevice64.dll (available here https://github.com/freezy/dmd-extensions/releases) unblocked in you VPinMame directory. Of course, if you have a real DMD connected that works in VPX, it will work with this button too. Just select a contiguous group of frames you want to see ingame and press the button, this window will be displayed along with the DMDs:



Everything is self-explanatory, the "x0.25"-"x32" buttons represent the play speed even if high speed won't be correct for short duration frames as the timer used is not efficient enough. For the playback, the duration associated to each frame (written in yellow in the frame strip) is used.
Let's just explain the "Load a dump" button: it lets you use a TXT dump file rather than the frame selection in the frame strip to be displayed.



We are now done with colorization, the remaining tool is used for the next part: The Sprites!

l/ Auto generate shadows around a selection



With this idea from Kraken, you can select any shape (with Ctrl), here the text in orange:



choose a colour in your drawing set (we take a black colour), then press one of these buttons showed above. The button on the top left add a shadow of the selected area in the top left, and so on. The central button add a shadow all around the selected area. Caution: if there is dynamic content where a shadow should be drawn, this shadow won't be added. Here is an example with the bottom right button:



Easy!

6/ Sprites



This part of our tuto is about this cool feature: moving items called sprites.

We have already seen in which situations to use them, now let's see how to create them.

[Pitfall warning]
You may draw in the Sprite window, but it is highly recommended to do all the colorization inside the Frame window before copying!
[/Pitfall warning]

a/ Create the sprite



To create a sprite, we must follow some steps in an order that is really important not to lose some informations we'll need after:

• In the Sprite window, type a name for your sprite in the top left edit box, then click
  
• In the Frame window, take time to figure out clearly the limits the sprite to avoid to miss something. To that end, display several frames where the sprite is. For example, in the above frame the motorcycle crossing the screen from right to left is a perfect subject to be a sprite. It is contoured by a black line to separate it from the items it passes in front of. And the center of the wheels is empty, so it doesn't cover the scenery below.
  
• You can then colorize it, something like this:
  
  
  
  
• Then select it for copy with its contour (pressing Ctrl) and click Copy or press Ctrl+C:
  
  
  
  
• Switch to Sprite window, be sure that you have the sprite you want to copy to active then click "Paste" or press Ctrl+V.
  Later on, if you want to know which frame you extracted the sprite from, you can click this button , it will display in the colorization window that frame. Of course, if this frame has been deleted, it will show you a wrong frame.
  

[Pitfall warning]

The sprite is tied to the frame it was extracted from as you can not modify the 64-colour palette inside the Sprite window!
So:
1/ if you are going to use the same sprite in several frames, be sure that the palette in the several frames are identical or copy it to all the frames from the frame the sprite is tied to
2/ if you modify the colours of the frame the sprite is tied to, if these colours are used by the sprite, its drawing will change accordingly
3/ if you delete the frame the sprite is tied to, the sprite will be tied to the frame after this one, so if the palette is different, the sprite will have an undetermined colorization in the Sprite window

[/Pitfall warning]

b/ Fine tune your colorization



You can modify your colorized sprite with the drawing and palette tools available. Once again you can not modify the 64-color palette with a right click on one of them.

c/ Detection areas



Your sprite is moving across the screen and may not be fully visible on it. So we are going to use rectangular detection masks to tell to the program what minimal parts will be detected to identify the presence of the sprite. You have up to 4 detection masks available for each sprite. Choose the one you want to define in the list box.

[Pitfall warning]
Sprites may be a little demanding in CPU resources, so:
1/ Use them when it is necessary
2/ The less the number of detection masks per sprite the better
3/ As we've already seen, even if you can look for up to 32 sprites per frame, the first 16 sprites found will be displayed. And they may be identical.

[/Pitfall warning]

You draw your detection masks on the left original shade-of-orange sprite. In our example, the motorcycle cross the screen from right to left and so we must set 2 detection masks, one at the front and one at the rear at the sprite.

CAUTION: To increase the efficiency of the sprite detection, the program first looks for 4 continuous pixels of the detection area and then compare the full detection area. So you detection masks MUST have a horizontal sequence of 4 active (in the sprite) pixels to be detected.

This next mask is OK, there are at least one continuous horizontal sequence of 4 pixels active inside the sprite:



[Pitfall warning]
As a detection area must be completely present in the frame to trigger the display of the sprite, make the detection masks:
- as small as possible to avoid the sprite not to be displayed if only a small part of it is in the frame
- but large enough not to confuse this part of the sprite with another part of the frame and so a sprite would be displayed anywhere not expected

[/Pitfall warning]

The button let you delete the current detection area.

d/ Assign a sprite to a frame

Sprite window:



Frame window:



Now that your sprite is complete, you must assign it to the frames where it has to be detected. Either use Sprite window's or Frame window's and each time the frame will be identified, the program will look for this sprite in it.

e/ List the frames that are using this sprite

With , you can choose in the dropdown list box which sprite you are looking for and then, on the list below, you'll see on which frames we try to detect this sprite.

That's all...

No...



f/ Redrawing the colorized scene without the sprite

Yes, you have understood well: we now must erase all traces of the sprite in the colorization frame (only for the static part)!
Why? Because the aim is to have only 1 frame for all the situations when the sprite is displayed!

Let's disgress for a moment:

In the comparison step, we are going to detect an area never covered by the sprite, so I said "1 frame", but in our case with the motorcycle, there is no static content that is never covered by the sprite, we must keep 3 different frames for the detection of the crossing of the sprite:





In the first frame @ebor and @peskopat only kept the top left part of the first "T" in "TO LIGHT" for comparison when the motorcycle is to the right of the screen.

I take the opportunity to show you that you often don't need a lot of static content to detect a frame, this really small comparison mask is enough in our whole ROM to trigger this only colorization at the right moment!

In the second frame, as the motorcycle is covering all the static content, they decided to consider the motorcycle as a static content and assign no sprite to this frame, just colorized it normally. The top left part of the "3" in "3 more" is masked as it may be any other digit.

Finally, in the third frame, they made as they did for the first frame doing the comparison step on the top right part of the last "T" in "TO LIGHT".

With these 3 frames, you cover the whole crossing of the motorcycle.
Disgression closed.

Once this is understood, we must, for the first and third frames in colorization mode erase the motorcycle as the scene will be rebuilt this way:

• The colorized frame will be displayed
  
• We look for the sprites in the inbound frame thanks to its detection areas
  
• If we found one, we draw the colorized version of it at the same position it was found
  

So if there are traces of the motorcycle on the colorized frame and the motorcycle is detected in the inbound frame somewhere else, when the program display the colorized sprite, it doesn't cover the traces that will be still visible!

To clean the frame from the sprite, we use all the other frames with the motorcycle at different positions and do "copy/paste"s. Eventually, we got this:



"I see some traces remaining of the motorcycle in the upper part of the frame!"

Yes, but that is OK because this upper part is dynamic content (it's not easy to see, but there is a purple frame around it), so ingame, this dynamic content with the motorcycle will display it at the right place and as it will be covered by the sprite, no problem! What is important is that the static part is cleaned of any traces of the motorcycle!

That's all for the sprites.


Be advise that the chapters 7  and more are at the bottom of this tuto.

9/ Testing and sharing your Serum

So now you're done, you've reached a milestone, what an achievement in your life: YOU ARE A COLORIZATION AUTHOR!

You want to test your Serum ingame. Even all along the creation process, you'd better test to check if everything is as you want.

Take the "name_of_the_rom.cRZ" file generated when you saved, put it in the "VPinMame\altcolor\name_of_the_rom\" directory (create it if it doesn't exist). For example, for the table Tron, copy "trn_174h.cRZ" to the directory "VPinMAME\altcolor\trn_174h".

You need a DmdDevice.dll compatible with the Serum file.
Take the latest Freezy's dmdext available here https://github.com/freezy/dmd-extensions/releases/ :

• Put the DmdDevice.dll and DmdDevice64.dll in your "VpinMame" directory (check that they are unblocked https://winaero.com/how-to-unblock-files-downloaded-from-internet-in-windows-10/)
  
• Put the DmdDevice.ini, if you don't have one already working and modify it according your needs.
  
• Ingame, press F1 then check "Use external DMD (dll)" and "Colorize DMD (4 colors)"
  
• Click "OK"
  
• Restart the table
  

Take the latest libserum available here https://github.com/zesinger/libserum/releases/tag/v1.6.0 :

• Put Serum.dll and Serum64.dll in your "VPinMame" directory (and unblock if needed)
  

You're done.

Ingame, don't hesitate to use the cheat mode (explained in the part about generating the dump file) to trigger the event you want to try.

The cRZ file is the only one you have to share to other people when you want to release your Serum.

I hope you enjoyed reading this and you will enjoy more to create Serum files.

Don't hesitate to join the Discord I created for help on using ColorizingDMD or for developers who want to work with Serum file format clicking here https://discord.gg/aK2dNaB6xR

10/ Keyboard and mouse commands reminder


a/ These are some shortcuts you may use:

• Ctrl+S: Save project
  
• Ctrl+Z: Undo
  
• Ctrl+Y: Redo
  
• Ctrl+M: Switch between the modes (Comparison <-> Colorization)
  
• Ctrl+F: Set the current displayed frame as the first frame in the frame strip
  
• Ctrl+C: Copy
  
• Ctrl+V: Paste. +K -> horizontal mirroring, +L -> vertical mirroring, +K+L -> both mirroring
  
• Ctrl+A: Select all the frame for comparison mask (in Comparison mode) or for copy (in Colorisation mode)
  
• Ctrl+D: Unselect all the frame for comparison mask (in Comparison mode) or for copy (in Colorisation mode)
  
• Ctrl+E: Completely remove any dynamic mask on the frame
  
• Left/Right: Change the current frame/sprite in the frame/sprite strip
  
• Ctrl+Left/Right: Move the frame strip to the next same frame (set it as the left frame in the frame strip)
  
• Shift+Left/Right: Move the frame strip to the next selected frame (set it as the left frame in the frame strip)
  
• W while selecting (with Ctrl): only the pixels different from 0 will be selected
  
• 2, 4, 6 and 8 on the numeric keypad while pasting (after pressing Paste or Ctrl+V): moving the selection to the bottom, left, right or top. Validate with Enter.
  
• Shift while validating paste (left click or Enter): only the pixels where the original source and destination frames are identical will be copied
  

b/ These are the different mouse actions:

Common for both mode:

• Mouse wheel with/out Shift key will move in the frame strip
  

Comparison mode:

• Left button for drawing the comparison mask
  

Colorization mode:

• Left button for colorization task (+Shift for re-initializing to original color)
  
• Right button for drawing the dynamic mask (+Shift for removing from the dynamic mask)
  
• Ctrl+Left button for drawing the copy mask (+Shift for removing from the copy mask)
  
• Alt+Left button in Magic Wand mode for colorizing all the pixels with the same color.
  
• Alt+Ctrl+Left button in Magic Wand mode for drawing the copy mask with all the pixels with the same color (+Shift for removing from the copy mask)
  
• While displaying the 64-color palette: Left click will select the color clicked / Right click will display the colour picker to create a new colour / Shift+Left click on a colour and release on another one will generate a gradient between these colours / Alt+Left click on a colour and release on another one will select the colours for the gradient draw
  
• While displaying the 64-color palette in color rotations: Shift+Left click on a colour and release on another one will select the colour span of the colour rotation
  
• Shift while clicking the "Animated GIF" button: the GIF generated will contain both the original and colorized frames
  

In the frame strip:

• Left button: If this frame is in the selection, but not the displayed one, it will be the new displayed one, but the selection will remain the same. If not, select the clicked frame alone.
  
• Ctrl+Left button: Add the clicked frame to the current selection
  
• Shift+Left button: Select the range between the previously selected frame and the one clicked
  
• Shift+Ctrl+Left button: Add the range described above to the current selection
  
• Alt+[Shift]+[Ctrl]+Left button: Do the same but DELETE to the current selection
  

7/ Importing images

With this new feature, you may import an image or a video to quickly colorize your frames.



Follow these steps:

a/ In the Frame window, select one or several frames.

b/ Then draw a copy selection where the image will be copied. It can be any shape you want, for example if you want to colorize the sky on this frame, draw the selection like this:



The whole area define an aspect ratio (here 128:20) that will be used and kept in the Image window. The only constraint is that the selection is at least 4x4 pixels.

c/ Switch to the Image window

d/ Open an image or video using to open a file or get an image using or press Ctrl+V to copy the content of the clipboard (if there is an image in it)

e/ If you use an image, the same content will be copied to all the selected frames in the frame strip, but if you use a video, the behaviour will depend on what you have here:

• With the "Hour", "Minute", "Second", "Frame" option, you select which time step is represented in the slider
  
• The slider lets you move along your video file according the chosen time option, the and buttons let you move one time unit before or after the current position
  
• Option "Copy this video image to all the selected frames" will behave as if you've opened an image
  
• Option "Use frame duration" will capture images in the video from the one selected on at interval determined by the frame durations (in yellow in the frame strip) to fill all the frame selected
  
• Option "Use a regular duration ... ms" will do the same except that you manually enter a regular value for duration
  
• Option
  

f/ The selection you made in the Frame window will be displayed now in the Image window with some parts darkened according to the aspect ratio and shape you fixed when selecting in the frame. Anyway you can resize the part not grayed with the mouse wheel or with these buttons . Pressing Shift at the same time will increase the number of pixels the frame is resized at once. The ratio will always remain the same.

g/ You can change the brightness and contrast of the image/video using the 2 sliders on the right



h/ Left click to select the part of the image to be downscaled to fit the selection (a red frame will be displayed around it)



i/ In the palette part of the toolbar, select the consecutive colours you want to use for that copy, at least 2, but the more, the better the image will be. For that, left click on the first colour and release the button on the last colour.

j/ Finally just press the "Copy" button and you can check the result on your frame/s.




k/ Scroll copy

As requested by MrMan2k7, will allow you to fill a contiguous selection of frames with a combination of zoom and move in the current image/ video frame selected.

Just do as before, but rather than selecting a single part of the screen with its zoom (mouse wheel) and position (left button), select another one with its own zoom (can be different) and position using the RIGHT mouse button. Then this second selection will have a green frame.
You then just need to press "Scroll Copy" and a progressive move and zoom from the red position/zoom to the green position/zoom will be calculated along the selected frames of the frame strip.
Be advise that this calculations may be long. It will be over when the button will be un-grayed.

8/ Backgrounds

Let's first explain the interest of the backgrounds: with dynamic content, you can not have a nice colorful background made from your artist skill as the whole area is calculated from the original. With this new feature, you decide that the colour 0 is the colour of the background and that any pixel originally colored in 0 will be replace with the corresponding pixel of the background. So if you have any dynamic content that does not use colour 0, it will be displayed above this background. This is particularly nice with frames made of text.
More, you can choose a rectangular bounding box for these backgrounds, so if in a frame you want to restrict the feature to a rectangular part, this is possible.

Imagine you have this original frame (with dynamic content and no use of colour 0 for this content):



and you've used the image importer to create a background out of a galaxy image, you get this:



If you define the upper part of the screen as the rectangular bounding box and assign this background (along with a dynamic colorization for the text using a red gradient for the 4th color used for the text), you get this:





So how can we do that?
First, to avoid recreating the full drawing tools from the frame window, the background window does not provide any drawing tool. You need to draw your background in the frame window in colorization mode on a trash frame.
No need to talk about Undo/Redo buttons.

a/ Create a new background from a colorized frame


When a colorized frame is ready to be imported as a background, just select it to be the one displayed in the Frame window then press this button in the background window. A new background is added with the appearance of the colorized frame.
Caution:

• only the fixed drawing is copied, the background is a fixed image, no dynamic content is copied.
  
• the 64-color palette and the colour rotations of the source colorized frame will be copied too
  

b/ and Modify the background

If you want to modify the background, select a trash frame in the frame window, be sure to be in colorization mode then press the export button. The content of the background will be copied to the frame. You can then modify it as you wish. Once done, click on the re-import button, then it will replace the content of the current selected background.

c/ Delete a background


Just press this button if you want to delete the background. If it is assigned to some frames, they won't have a background assigned any more.

d/ Assign a background to a selection of frames


If you want to assign a background to some selected frames, select them in the Frame window. Now, you must define a bounding box for the background, so use the copy selection (with Ctrl, so), select a rectangle (or whatever the shape you select, the rectangle containing the whole selection will be used) in this Frame window. If you don't want to limit to any area, just select all (Ctrl+A).
Come back to the background window and click this button, and that's all.
Important: The 64-color palette and the colour rotations of the background will be copied to the colorized frame, so you'd better:

• limit the number of colours of your background to keep some colors for the rest of the colorization
  
• assign backgrounds BEFORE colorizing your frames if you don't want the palette you spent a lot of time to create to be a big mess.
  

That's all!

e/ List all the frames using this background

The part of the toolbar let you check which frames are using the current selected background. Just open the drop down list and if you want to see the corresponding frame, click on it then it will be the first frame in the frame strip of the main window.