In the OSLib documentation, you will often come across a term called "swizzling." This concept is particularly important when working with images in the PSP's graphics system, and understanding it can greatly impact the performance of your application.

Image swizzling is a process that reorganizes the arrangement of pixels in an image to better align with the memory access patterns of the graphics processor (GPU). The GPU reads image data in a specific way, and swizzling ensures that the pixels are ordered in a manner that optimizes this reading process. As a result, the GPU can render swizzled images much faster than unswizzled ones, leading to significant performance improvements in graphics rendering, particularly when images are stored in RAM and frequently accessed.

However, this performance gain comes with certain drawbacks. When an image is swizzled, the pixels are no longer stored contiguously in memory as they would be in a traditional, linear image. This discontinuity complicates direct pixel manipulation because the straightforward method of accessing a pixel by its x and y coordinates no longer applies. Instead, you would need to perform complex calculations to determine the actual position of a specific pixel within the swizzled data. This complexity can make tasks like real-time image modification or pixel-based effects much more challenging and computationally expensive.

For example, if you are working on an old-school framebuffer demo or any other application where you need to access and modify individual pixels frequently and directly, you would benefit from using unswizzled (normal) images. Unswizzled images store pixel data in a linear fashion, making it easy to access and manipulate individual pixels using simple arithmetic based on their coordinates.

On the other hand, if your images are loaded from files and are intended primarily for rendering rather than modification, it is advisable to use swizzled images. The performance benefits are particularly noticeable when these images are placed in RAM, as swizzled images allow the GPU to render them more efficiently, reducing the load on the system and enabling smoother graphics performance.

In OSLib, the image loading process is designed with this in mind. By default, when you load an image from a file using functions like oslLoadImageFile, OSLib will automatically swizzle the image data to optimize rendering performance. However, if you manually create an image using functions like oslCreateImage, OSLib will not swizzle the image by default, giving you the flexibility to choose the format that best suits your needs.

If, for any reason, you prefer not to have the images swizzled automatically when loading them from files, you can disable this behavior. By passing the OSL_UNSWIZZLED flag during the image loading process, you can instruct OSLib to keep the image in its unswizzled state, which might be preferable for certain applications where direct pixel manipulation is required. For more information on how to control this behavior, see oslSetImageAutoSwizzle.