| Oyranos Colour Management System API

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

Public Member Functions | Data Fields
oyPixelAccess_s Struct Reference
DAG and Image processing API

Control pixel access order. More...

`#include <oyPixelAccess_s.h>`

Inheritance diagram for oyPixelAccess_s:
Collaboration diagram for oyPixelAccess_s:

## Public Member Functions
OYAPI oyPixelAccess_s *OYEXPORT | oyPixelAccess_New (oyObject_s object)
| allocate a new PixelAccess object More...
OYAPI oyPixelAccess_s *OYEXPORT | oyPixelAccess_Copy (oyPixelAccess_s *pixelaccess, oyObject_s object)
| copy or reference a PixelAccess object More...
OYAPI int OYEXPORT | oyPixelAccess_Release (oyPixelAccess_s **pixelaccess)
| release and possibly deallocate a oyPixelAccess_s object More...
oyPixelAccess_s * | oyPixelAccess_Create (int32_t start_x, int32_t start_y, oyFilterPlug_s *plug, oyPIXEL_ACCESS_TYPE_e type, oyObject_s object)
| Allocate iand initialise a basic oyPixelAccess_s object. More...
oyImage_s * | oyPixelAccess_GetOutputImage (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::output_image. More...
int | oyPixelAccess_SetOutputImage (oyPixelAccess_s *pixel_access, oyImage_s *image)
| Set oyPixelAccess_s::output_image. More...
oyRectangle_s * | oyPixelAccess_GetOutputROI (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::output_image_roi. More...
oyFilterGraph_s * | oyPixelAccess_GetGraph (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::graph. More...
oyOptions_s * | oyPixelAccess_GetRequestQueue (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::request_queue. More...
oyArray2d_s * | oyPixelAccess_GetArray (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::array. More...
int | oyPixelAccess_SetArray (oyPixelAccess_s *pixel_access, oyArray2d_s *array)
| Set oyPixelAccess_s::array. More...
oyStruct_s * | oyPixelAccess_GetUserData (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::user_data. More...
int | oyPixelAccess_SetUserData (oyPixelAccess_s *pixel_access, oyStruct_s *user_data)
| Set oyPixelAccess_s::user_data. More...
int32_t | oyPixelAccess_GetWorkspaceID (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::workspace_id. More...
int | oyPixelAccess_SetWorkspaceID (oyPixelAccess_s *pixel_access, int32_t workspace_id)
| Set oyPixelAccess_s::workspace_id. More...
double | oyPixelAccess_GetStart (oyPixelAccess_s *pixel_access, int vertical)
| Access oyPixelAccess_s::start_xy. More...
double | oyPixelAccess_GetOldStart (oyPixelAccess_s *pixel_access, int vertical)
| Access oyPixelAccess_s::start_xy_old. More...
int | oyPixelAccess_SetOldStart (oyPixelAccess_s *pixel_access, int vertical, double start)
| Access oyPixelAccess_s::start_xy_old. More...
Public Member Functions inherited from oyStruct_s
const char * | oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
| get a text dump More...

## Data Fields
oyStruct_Copy_f | copy
oyStruct_Release_f | release
Data Fields inherited from oyStruct_s
oyStruct_Copy_f | copy
oyStruct_Release_f | release

## Detailed Description

Control pixel access order.

A struct to control pixel access. It is a kind of flexible pixel iterator. The order or pattern of access is defined by the [array_xy and] start_[x,y] variables.

oyPixelAccess_s is like a job ticket. Goal is to maintain all intermediate and processing dependend memory references in this structure.

[The index variable specifies the iterator position in the array_xy index array.]

[pixels_n says how many pixels are to be processed for the cache. pixels_n is used to calculate the buffers located with getBuffer and freeBuffer. The amount of pixel specified in pixels_n must be processed by each filter, because other filters are relying on a properly filled cache. This variable also determins the size of the next iteration.]

[The relation of pixels_n to array_xy and start_[x,y] is that a minimum of pixels_n must be processed by starting with start_[x,y] and processing pixels_n through array_xy. array_xy specifies the offset pixel distance to a next pixel in x and y directions. In case pixels_n is larger than array_n the array_xy has to be continued at array_xy[0,1] after reaching its end (array_n).
Example:
Thus a line iterator behaviour can be specified by simply setting array_xy = {1,0}, for a advancement in x direction of one, array_n = 1, as we need just this type of advancement and pixels_n = image_width, for saying how often the pattern descibed in array_xy has to be applied.]

Handling of pixel access is to be supported by a filter in a function of type oyCMMFilter_GetNext_f() in oyCMMapi4_s::oyCMMConnector_GetNext().

Access to the buffers by concurrenting threads is handled by passing different oyPixelAccess_s objects per thread.

From the module point of view it is a requirement to obtain the intermediate buffers from somewhere. These are the ones to read from and to write computed results into.
Pixel in- and output buffers separation:

- Copy the output area and request to manipulate it by each filter. There is no overwriting of results. Reads a bit fixed. How can filters decide upon the input size? However, if a filter works on more than one dimension, it can opt to get its area directly from a input mediator. -[Provide a opaque output and input area and request to copy by each filter. Filters would overwrite previous manipulations or some mechanism of swapping the input with the output side is needed.]
- Some filters want different input and output areas. They see the mediator as the previous, or the input, element in the graph.
- Will the mediators always be visible in order to get all informations about the image? During setting up the graph this should be handled.

Access to input and output buffers:

- The output oyArray2d_s is to be reserved only.
- The input oyArray2d_s is to be provided for multi dimensional manipulators directly from the input mediator.

Thread synchronisation:

- The oyArray2d_s is a opaque memory blob. So different filters can act upon this resource. It would be in the resposiblity of the graph to avoid conflicts like using the same output for different manipulations. Given that the output is acting actively, the potential is small anyway.
- The input should be neutral and not directly manipulated. What can happen is that different threads request the same input area and the according data is to be rendered first. So this easily could end in rendering two times for the same result. Some scheduling in the mediators may help solving this and improove on performance.

Area dimensions:

- One point is very simple to provide. It may easily require additional preparations for area manipulations like blur.
- Line is the next hard. The advantage it is still simple and speed efficient. Programming is a bit more demanding.
- Areas of pixel are easy to provide through oyArray2d_s. It can include the above two cases.
- Pattern accessors are very flexible for manipulators. It's not clear how the resulting complexity of translating the pattern to a array with known pixel positions can be hidden from other filters, which need to know about positions. One strategy would be to use mediators. They can request the according pixels from previous filters. A function to convert the pattern to a list of positions should be provided. Very elegant, but probably better to do later after oyArray2d_s.

Possible strategies are (old text):

- Use mediators to convert between different pixel layouts and areas. These could cache the record of a successful query. Mediators are Nodes in the graph. As the graph and thus mediators can be accessed over concurrenting entries a cache tends to be expensive.
- The oyPixelAccess_s could hold caches instead of mediators. It is the structure, which is owned by a given thread anyway. oyPixelAccess_s needs two buffers one for input and one for output. As the graph is asked to provide the next pixel via a oyPixelAccess_s struct, this struct must be associated with source and destination buffers. The mediator on output has to search through the chain for the previous mediator and ask there for the input buffer. The ouput buffer is provided by this mediator itself. These two buffers are set as the actual ones for processing by the normal filters. It must be clear, what is a mediator, for this scheme to work. As a mediator is reached in the processing graph, its task is not only to convert between buffers but as well to update the oyPixelAccess_s struct with the next mediators and its own buffer. Thus the next inbetween filters can process on their part. One advantage is that the mediators can pass their buffers to oyPixelAccess_s, which are independent to threads and can be shared.
- Each filter obtains a buffer being asked to fill it with the pixels positions described in oyPixelAccess_s. A filter is free to create a new oyPixelAccess_s description and obtain for instance the surounding of the requested pixels. There is no caching to be expected other than in the oyPixelAccess_s own output buffer.

Todo:
  clear about pixel buffer copying, how to reach the buffers, thread synchronisation, simple or complex pixel areas (point, line, area, pattern )

     Relation of positional parameters:

                 start_xy         output_image_roi
                    |                /
              +-----|---------------/--------------+
     original |     |              /               |
     image ---+     |             /                |
              |  ---+------------/----------+      |
              |     |           /           +---------- output_image
              |     |   +------+--------+   |      |
              |     |   |               |   |      |
              |     |   |               |   |      |
              |     |   +---------------+   |      |
              |     |                       |      |
              |     +-----------------------+      |
              |                                    |
              +------------------------------------+

Version
  Oyranos: 0.1.10

Since
  2008/07/04 (Oyranos: 0.1.8)

Date
  2009/05/05

## Member Function Documentation

OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_Copy | ( | oyPixelAccess_s * | pixelaccess,
|  | oyObject_s | object
| ) |  |

copy or reference a PixelAccess object

Function oyPixelAccess_Copy

The function is for copying and for referencing. The reference is the most often used way, which saves resourcs and time.

Parameters

  [in] | pixelaccess | PixelAccess struct object
  | object | NULL - means reference, the optional object triggers a real copy

References oyOBJECT_PIXEL_ACCESS_S.

oyPixelAccess_s * oyPixelAccess_Create | ( | int32_t | start_x,
|  | int32_t | start_y,
|  | oyFilterPlug_s * | plug,
|  | oyPIXEL_ACCESS_TYPE_e | type,
|  | oyObject_s | object
| ) |  |

Allocate iand initialise a basic oyPixelAccess_s object.

Function oyPixelAccess_Create

      // conversion->out_ has to be linear, so we access only the first plug
      node = oyConversion_GetNode( conversion, OY_OUTPUT );
      plug = oyFilterNode_GetPlug( node, 0 );
      oyFilterNode_Release( &node );

      // create a very simple pixel iterator
      if(plug)
        pixel_access = oyPixelAccess_Create( 0,0, plug,
                                             oyPIXEL_ACCESS_IMAGE, 0 );

    @version Oyranos: 0.1.10
    @since   2008/07/07 (Oyranos: 0.1.8)
    @date    2009/06/10

The filters have no obligation to pass end to end informations. The ticket must hold all pices of interesst.

Todo:
  how can we know about the various module capabilities
  - back report the processed number of pixels in the passed pointer
  - restrict for a line interface only, would fit to oyArray2d_s
  - + handle inside an to be created function oyConversion_RunPixels()

References oyBOOLEAN_INTERSECTION, oyFilterNode_s::oyFilterGraph_FromNode(), oyImage_s::oyImage_Copy(), oyImage_s::oyImage_GetHeight(), oyImage_s::oyImage_GetWidth(), oyOptions_s::oyOptions_Filter(), oyPIXEL_ACCESS_LINE, oyPIXEL_ACCESS_POINT, oyPixelAccess_New(), and oyPixelAccess_Release().

Referenced by oyConversion_s::oyConversion_GetImage(), and oyConversion_s::oyConversion_RunPixels().

oyArray2d_s * oyPixelAccess_GetArray | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::array.

Function oyPixelAccess_GetArray

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyArray2d_s::oyArray2d_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

oyFilterGraph_s * oyPixelAccess_GetGraph | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::graph.

Function oyPixelAccess_GetGraph

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyFilterGraph_s::oyFilterGraph_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

double oyPixelAccess_GetOldStart | ( | oyPixelAccess_s * | pixel_access,
|  | int | vertical
| ) |  |

Access oyPixelAccess_s::start_xy_old.

Function oyPixelAccess_GetOldStart

Version
  Oyranos: 0.5.0

Date
  2012/09/10

Since
  2012/09/10 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

oyImage_s * oyPixelAccess_GetOutputImage | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::output_image.

Function oyPixelAccess_GetOutputImage

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyImage_s::oyImage_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

oyRectangle_s * oyPixelAccess_GetOutputROI | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::output_image_roi.

Function oyPixelAccess_GetOutputROI

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S, and oyRectangle_s::oyRectangle_Copy().

oyOptions_s * oyPixelAccess_GetRequestQueue | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::request_queue.

Function oyPixelAccess_GetRequestQueue

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S, and oyOptions_s::oyOptions_Copy().

double oyPixelAccess_GetStart | ( | oyPixelAccess_s * | pixel_access,
|  | int | vertical
| ) |  |

Access oyPixelAccess_s::start_xy.

Function oyPixelAccess_GetStart

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

oyStruct_s * oyPixelAccess_GetUserData | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::user_data.

Function oyPixelAccess_GetUserData

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References copy, and oyOBJECT_PIXEL_ACCESS_S.

int32_t oyPixelAccess_GetWorkspaceID | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::workspace_id.

Function oyPixelAccess_GetWorkspaceID

A ID for distinct resources.

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_New | ( | oyObject_s | object | ) |

allocate a new PixelAccess object

Function oyPixelAccess_New

References oyOBJECT_OBJECT_S.

Referenced by oyPixelAccess_Create().

OYAPI int OYEXPORT oyPixelAccess_Release | ( | oyPixelAccess_s ** | pixelaccess | ) |

release and possibly deallocate a oyPixelAccess_s object

Function oyPixelAccess_Release

Parameters

  [in,out] | pixelaccess | PixelAccess struct object

References oyOBJECT_PIXEL_ACCESS_S.

Referenced by oyConversion_s::oyConversion_GetImage(), oyConversion_s::oyConversion_RunPixels(), and oyPixelAccess_Create().

int oyPixelAccess_SetArray | ( | oyPixelAccess_s * | pixel_access,
|  | oyArray2d_s * | array
| ) |  |

Set oyPixelAccess_s::array.

Function oyPixelAccess_SetArray

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyArray2d_s::oyArray2d_Copy(), oyArray2d_s::oyArray2d_Release(), and oyOBJECT_PIXEL_ACCESS_S.

int oyPixelAccess_SetOldStart | ( | oyPixelAccess_s * | pixel_access,
|  | int | vertical,
|  | double | start
| ) |  |

Access oyPixelAccess_s::start_xy_old.

Function oyPixelAccess_SetOldStart

Version
  Oyranos: 0.5.0

Date
  2012/09/10

Since
  2012/09/10 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

int oyPixelAccess_SetOutputImage | ( | oyPixelAccess_s * | pixel_access,
|  | oyImage_s * | image
| ) |  |

Set oyPixelAccess_s::output_image.

Function oyPixelAccess_SetOutputImage

Version
  Oyranos: 0.5.0

Date
  2012/10/04

Since
  2012/10/04 (Oyranos: 0.5.0)

References oyImage_s::oyImage_Copy(), oyImage_s::oyImage_Release(), and oyOBJECT_PIXEL_ACCESS_S.

int oyPixelAccess_SetUserData | ( | oyPixelAccess_s * | pixel_access,
|  | oyStruct_s * | user_data
| ) |  |

Set oyPixelAccess_s::user_data.

Function oyPixelAccess_SetUserData

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyStruct_s::copy, and oyOBJECT_PIXEL_ACCESS_S.

int oyPixelAccess_SetWorkspaceID | ( | oyPixelAccess_s * | pixel_access,
|  | int32_t | workspace_id
| ) |  |

Set oyPixelAccess_s::workspace_id.

Function oyPixelAccess_SWorkspaceID

A ID for distinct resources.

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

## Field Documentation

oyStruct_Copy_f oyPixelAccess_s::copy

copy function

Referenced by oyPixelAccess_GetUserData().

oyStruct_Release_f oyPixelAccess_s::release

release function